harness-alchemist 0.1.0

package/lib/validate.mjs

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs"
+import { readdir, readFile, realpath } from "node:fs/promises"
+import { basename, dirname, join, resolve, sep } from "node:path"
+import { fileURLToPath } from "node:url"
+import { spawnSync } from "node:child_process"
+
+const REQUIRED_FILES = [
+  ".agents/plugins/marketplace.json",
+  ".claude-plugin/marketplace.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  ".github/workflows/npm-publish.yml",
+  ".gitignore",
+  "AGENTS.md",
+  "LICENSE",
+  "README.md",
+  "cordis.patch.yml",
+  "package.json",
+  "plugin.json",
+  "src/deepseek.ts",
+  "src/opencode.ts",
+  "tsconfig.json",
+]
+
+function usage() {
+  return `Usage: harness-alchemist validate [project-directory] [--external] [--json]
+
+Validates a universal Claude, Codex, OpenCode, Antigravity, and DeepSeek
+plugin scaffold. By default the project is resolved from the current working
+directory or from the script's containing generated project.
+
+Options:
+  --external  Run installed platform validators, currently Claude Code.
+  --json      Print a machine-readable result.
+  --help      Show this help.`
+}
+
+function findProjectRoot(start) {
+  let current = resolve(start)
+  while (true) {
+    if (
+      existsSync(join(current, "package.json")) &&
+      existsSync(join(current, ".claude-plugin")) &&
+      existsSync(join(current, ".codex-plugin"))
+    ) {
+      return current
+    }
+    const parent = dirname(current)
+    if (parent === current) return undefined
+    current = parent
+  }
+}
+
+function parseArgs(argv) {
+  let project
+  let external = false
+  let json = false
+
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") return { help: true }
+    if (arg === "--external") external = true
+    else if (arg === "--json") json = true
+    else if (arg.startsWith("-")) throw new Error(`Unknown option: ${arg}`)
+    else if (project) throw new Error("Only one project directory may be supplied")
+    else project = arg
+  }
+
+  return { project, external, json, help: false }
+}
+
+async function readJson(path, errors) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"))
+  } catch (error) {
+    errors.push(`${path}: invalid JSON (${error.message})`)
+    return undefined
+  }
+}
+
+function unquote(value) {
+  const trimmed = value.trim()
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1)
+  }
+  return trimmed
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith("---\n")) return undefined
+  const end = content.indexOf("\n---", 4)
+  if (end < 0) return undefined
+  const block = content.slice(4, end)
+  const values = {}
+  for (const line of block.split("\n")) {
+    const match = line.match(/^([a-zA-Z0-9-]+):\s*(.*)$/)
+    if (match) values[match[1]] = unquote(match[2])
+  }
+  return values
+}
+
+function parseYamlScalar(value) {
+  const scalar = value.trim()
+  if (scalar.startsWith("'") && scalar.endsWith("'")) {
+    return scalar.slice(1, -1).replaceAll("''", "'")
+  }
+  if (scalar.startsWith('"') && scalar.endsWith('"')) {
+    try {
+      return JSON.parse(scalar)
+    } catch {
+      return undefined
+    }
+  }
+  return /^[A-Za-z0-9@/_.-]+$/.test(scalar) ? scalar : undefined
+}
+
+function parseCordisInsertEntries(content) {
+  if (content.includes("\t")) return []
+  const lines = content.split("\n")
+  const entries = []
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const insertMatch = lines[index].match(/^(\s*)-\s+insert:\s*(?:#.*)?$/)
+    if (!insertMatch || insertMatch[1].length !== 0) continue
+
+    let entryIndent
+    for (let next = index + 1; next < lines.length; next += 1) {
+      const line = lines[next]
+      if (line.trim() && line.search(/\S/) === 0) break
+      if (!line.trim() || line.trimStart().startsWith("#")) continue
+      const idMatch = line.match(/^(\s*)-\s+id:\s*(.+?)\s*$/)
+      if (entryIndent === undefined) {
+        if (!idMatch || idMatch[1].length === 0) break
+        entryIndent = idMatch[1].length
+      }
+      if (!idMatch || idMatch[1].length !== entryIndent) continue
+      const id = parseYamlScalar(idMatch[2])
+      if (!id) continue
+
+      const idIndent = idMatch[1].length
+      let name
+      let nameFields = 0
+      for (let field = next + 1; field < lines.length; field += 1) {
+        const fieldLine = lines[field]
+        const fieldIndent = fieldLine.search(/\S/)
+        if (fieldLine.trim() && fieldIndent <= idIndent) break
+        const nameMatch = fieldLine.match(/^(\s*)name:\s*(.+?)\s*$/)
+        if (nameMatch && nameMatch[1].length === idIndent + 2) {
+          nameFields += 1
+          name = parseYamlScalar(nameMatch[2])
+        }
+      }
+      entries.push({ id, name, valid: name !== undefined && nameFields === 1 })
+    }
+  }
+
+  return entries
+}
+
+async function collectSkillFiles(root, relativeRoot) {
+  const start = join(root, relativeRoot)
+  if (!existsSync(start)) return []
+  const results = []
+
+  async function walk(directory, depth) {
+    if (depth > 5) return
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name)
+      if (entry.isDirectory()) await walk(path, depth + 1)
+      else if (entry.isFile() && entry.name === "SKILL.md") results.push(path)
+    }
+  }
+
+  await walk(start, 0)
+  return results
+}
+
+async function scanForTokens(root) {
+  const matches = []
+  const ignored = new Set([".git", "dist", "node_modules", "coverage", "templates"])
+
+  async function walk(directory, depth) {
+    if (depth > 8) return
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      if (ignored.has(entry.name)) continue
+      const path = join(directory, entry.name)
+      if (entry.isDirectory()) {
+        await walk(path, depth + 1)
+      } else if (entry.isFile()) {
+        const content = await readFile(path, "utf8").catch(() => "")
+        if (/\{\{[A-Z0-9_]+\}\}/.test(content)) matches.push(path)
+      }
+    }
+  }
+
+  await walk(root, 0)
+  return matches
+}
+
+function requirePath(root, relativePath, errors) {
+  if (!existsSync(join(root, relativePath))) errors.push(`Missing required file: ${relativePath}`)
+}
+
+async function requireManifestPath(root, value, label, errors) {
+  if (typeof value !== "string" || !value.startsWith("./")) {
+    errors.push(`${label} must be a ./-relative path`)
+    return
+  }
+  const target = resolve(root, value)
+  if (!(target === root || target.startsWith(`${root}${sep}`))) {
+    errors.push(`${label} escapes the plugin root`)
+  } else if (!existsSync(target)) {
+    errors.push(`${label} points to missing path ${value}`)
+  } else {
+    const [canonicalRoot, canonicalTarget] = await Promise.all([realpath(root), realpath(target)])
+    if (!(canonicalTarget === canonicalRoot || canonicalTarget.startsWith(`${canonicalRoot}${sep}`))) {
+      errors.push(`${label} resolves through a symlink outside the plugin root`)
+    }
+  }
+}
+
+function exportTarget(exports, key, field = "import") {
+  const value = exports?.[key]
+  if (typeof value === "string") return value
+  if (value && typeof value === "object") return value[field]
+  return undefined
+}
+
+export async function validateProject(projectRoot, options = {}) {
+  const root = resolve(projectRoot)
+  const errors = []
+  const warnings = []
+
+  for (const file of REQUIRED_FILES) requirePath(root, file, errors)
+  if (errors.length > 0) return { root, errors, warnings }
+
+  const packageJson = await readJson(join(root, "package.json"), errors)
+  const claudePlugin = await readJson(join(root, ".claude-plugin/plugin.json"), errors)
+  const claudeMarketplace = await readJson(
+    join(root, ".claude-plugin/marketplace.json"),
+    errors,
+  )
+  const codexPlugin = await readJson(join(root, ".codex-plugin/plugin.json"), errors)
+  const codexMarketplace = await readJson(
+    join(root, ".agents/plugins/marketplace.json"),
+    errors,
+  )
+  const antigravityPlugin = await readJson(join(root, "plugin.json"), errors)
+
+  if (errors.length > 0) return { root, errors, warnings }
+
+  const packageBase = packageJson.name?.split("/").at(-1)
+  const pluginName = claudePlugin.name
+  const validName = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+  if (!validName.test(pluginName ?? "")) {
+    errors.push("Plugin name must contain lowercase letters, digits, and single hyphens")
+  }
+  if ((pluginName?.length ?? 0) > 56) {
+    errors.push("Plugin name must be at most 56 characters")
+  }
+  if (packageBase !== pluginName) {
+    errors.push(`npm package basename '${packageBase}' must match plugin name '${pluginName}'`)
+  }
+
+  for (const [label, value] of [
+    ["Codex plugin", codexPlugin.name],
+    ["Antigravity plugin", antigravityPlugin.name],
+  ]) {
+    if (value !== pluginName) errors.push(`${label} name '${value}' does not match '${pluginName}'`)
+  }
+
+  for (const [label, manifest] of [
+    ["Claude plugin", claudePlugin],
+    ["Codex plugin", codexPlugin],
+  ]) {
+    if (manifest.version !== packageJson.version) {
+      errors.push(`${label} version does not match package.json`)
+    }
+    if (manifest.description !== packageJson.description) {
+      errors.push(`${label} description does not match package.json`)
+    }
+  }
+  if (antigravityPlugin.description !== packageJson.description) {
+    errors.push("Antigravity description does not match package.json")
+  }
+
+  if (packageJson.type !== "module") errors.push("package.json type must be 'module'")
+  if (packageJson.engines?.node !== ">=22.20.0") {
+    errors.push("package.json engines.node must be '>=22.20.0'")
+  }
+  const requiredExports = [
+    [".", "import", "./dist/opencode.js"],
+    [".", "types", "./dist/opencode.d.ts"],
+    ["./deepseek", "import", "./dist/deepseek.js"],
+    ["./deepseek", "types", "./dist/deepseek.d.ts"],
+    ["./cordis.patch.yml", "import", "./cordis.patch.yml"],
+  ]
+  for (const [key, field, expected] of requiredExports) {
+    const target = exportTarget(packageJson.exports, key, field)
+    if (target !== expected) {
+      errors.push(`package.json export '${key}' ${field} target must be '${expected}'`)
+    }
+  }
+  for (const entry of [
+    "dist",
+    "skills",
+    "cordis.patch.yml",
+    ".claude-plugin/plugin.json",
+    ".codex-plugin/plugin.json",
+    "plugin.json",
+  ]) {
+    if (!packageJson.files?.includes(entry)) errors.push(`package.json files is missing '${entry}'`)
+  }
+  if (packageJson.dsh?.bundle?.patch !== "./cordis.patch.yml") {
+    errors.push("package.json dsh.bundle.patch must be './cordis.patch.yml'")
+  }
+
+  await requireManifestPath(root, claudePlugin.skills, "Claude skills", errors)
+  await requireManifestPath(root, codexPlugin.skills, "Codex skills", errors)
+
+  const claudeEntry = claudeMarketplace.plugins?.find((entry) => entry.name === pluginName)
+  if (!claudeEntry) errors.push("Claude marketplace is missing the plugin entry")
+  else if (claudeEntry.source !== "./") errors.push("Claude marketplace source must be './'")
+
+  const codexEntry = codexMarketplace.plugins?.find((entry) => entry.name === pluginName)
+  if (!codexEntry) errors.push("Codex marketplace is missing the plugin entry")
+  else {
+    if (codexEntry.source?.source !== "local" || codexEntry.source?.path !== "./") {
+      errors.push("Codex marketplace source must be a local './' path")
+    }
+    if (!codexEntry.policy?.installation || !codexEntry.policy?.authentication) {
+      errors.push("Codex marketplace entry requires installation and authentication policies")
+    }
+    if (!codexEntry.category) errors.push("Codex marketplace entry requires a category")
+  }
+
+  const patch = await readFile(join(root, "cordis.patch.yml"), "utf8")
+  const expectedModule = `${packageJson.name}/deepseek`
+  const cordisEntries = parseCordisInsertEntries(patch)
+    .filter((entry) => entry.id === pluginName)
+  const cordisEntry = cordisEntries[0]
+  if (cordisEntries.length !== 1 || !cordisEntry?.valid) {
+    errors.push(`cordis.patch.yml must contain a valid insert entry for '${pluginName}'`)
+  } else if (cordisEntry.name !== expectedModule) {
+    errors.push(`cordis.patch.yml entry '${pluginName}' must load '${expectedModule}'`)
+  }
+
+  const skillFiles = [
+    ...(await collectSkillFiles(root, "skills")),
+    ...(await collectSkillFiles(root, ".agents/skills")),
+  ]
+  if (skillFiles.length < 2) errors.push("Expected a shared skill and a project development skill")
+
+  for (const skillFile of skillFiles) {
+    const frontmatter = parseFrontmatter(await readFile(skillFile, "utf8"))
+    const directoryName = basename(dirname(skillFile))
+    if (!frontmatter) errors.push(`${skillFile}: missing YAML frontmatter`)
+    else {
+      if (frontmatter.name !== directoryName) {
+        errors.push(`${skillFile}: frontmatter name must match directory '${directoryName}'`)
+      }
+      if (!frontmatter.description) errors.push(`${skillFile}: description is required`)
+      if (!validName.test(frontmatter.name ?? "") || (frontmatter.name?.length ?? 0) > 64) {
+        errors.push(`${skillFile}: invalid Agent Skill name`)
+      }
+    }
+  }
+
+  for (const path of await scanForTokens(root)) {
+    errors.push(`${path}: unresolved scaffold token`)
+  }
+
+  if (options.external) {
+    const result = spawnSync("claude", ["plugin", "validate", root, "--strict"], {
+      encoding: "utf8",
+    })
+    if (result.error?.code === "ENOENT") warnings.push("Claude CLI not found; skipped external validation")
+    else if (result.status !== 0) {
+      errors.push(`Claude plugin validation failed: ${(result.stderr || result.stdout).trim()}`)
+    }
+  }
+
+  return { root, errors, warnings }
+}
+
+export async function runValidate(argv) {
+  let args
+  try {
+    args = parseArgs(argv)
+  } catch (error) {
+    console.error(error.message)
+    console.error(usage())
+    return 2
+  }
+
+  if (args.help) {
+    console.log(usage())
+    return 0
+  }
+
+  const scriptDirectory = dirname(fileURLToPath(import.meta.url))
+  const root = args.project
+    ? resolve(args.project)
+    : findProjectRoot(process.cwd()) ?? findProjectRoot(scriptDirectory)
+
+  if (!root) {
+    console.error("Could not find a universal plugin project. Pass its directory explicitly.")
+    return 2
+  }
+
+  const result = await validateProject(root, { external: args.external })
+  if (args.json) {
+    console.log(JSON.stringify({ valid: result.errors.length === 0, ...result }, null, 2))
+  } else if (result.errors.length === 0) {
+    console.log(`Validated universal plugin scaffold at ${result.root}`)
+    for (const warning of result.warnings) console.warn(`Warning: ${warning}`)
+  } else {
+    console.error(`Validation failed for ${result.root}:`)
+    for (const error of result.errors) console.error(`- ${error}`)
+    for (const warning of result.warnings) console.warn(`Warning: ${warning}`)
+  }
+
+  return result.errors.length > 0 ? 1 : 0
+}
+
+if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) {
+  process.exitCode = await runValidate(process.argv.slice(2))
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "harness-alchemist",
+  "version": "0.1.0",
+  "description": "Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex, OpenCode, Antigravity, and DeepSeek Harness.",
+  "type": "module",
+  "bin": {
+    "harness-alchemist": "./bin/harness-alchemist.mjs"
+  },
+  "main": "./dist/opencode.js",
+  "types": "./dist/opencode.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/opencode.d.ts",
+      "import": "./dist/opencode.js"
+    },
+    "./deepseek": {
+      "types": "./dist/deepseek.d.ts",
+      "import": "./dist/deepseek.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "lib",
+    "templates",
+    "skills",
+    "cordis.patch.yml",
+    ".claude-plugin/plugin.json",
+    ".codex-plugin/plugin.json",
+    "plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "sync": "node .agents/skills/develop-harness-alchemist/scripts/sync-metadata.mjs",
+    "validate": "node .agents/skills/develop-harness-alchemist/scripts/validate.mjs",
+    "pack:check": "node .agents/skills/develop-harness-alchemist/scripts/check-package.mjs",
+    "verify": "npm run check && npm test && npm run validate && npm run pack:check",
+    "prepack": "npm run verify"
+  },
+  "engines": {
+    "node": ">=22.20.0",
+    "bun": ">=1.2.0"
+  },
+  "keywords": [
+    "agent-skill",
+    "antigravity",
+    "claude-code",
+    "codex",
+    "deepseek",
+    "opencode",
+    "scaffolding"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@opencode-ai/plugin": "^1.18.21"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@opencode-ai/plugin": "^1.18.21",
+    "typescript": "^5.9.3"
+  },
+  "author": "Haochuan Zhang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lunarmoon26/harness-alchemist"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/plugin.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "harness-alchemist",
+  "description": "Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex, OpenCode, Antigravity, and DeepSeek Harness."
+}

package/skills/harness-alchemist/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: harness-alchemist
+description: "Use the Harness Alchemist CLI to create or validate universal coding-agent plugins for Claude Code, Codex/ChatGPT, OpenCode, Google Antigravity, and DeepSeek Harness/Cordis."
+compatibility: Requires Node.js 22.20+ or Bun 1.2+ for the CLI. Platform CLIs are optional and only needed for live installation checks.
+---
+
+# Harness Alchemist
+
+Use the CLI to create or validate a universal plugin repository. This is the
+tier-2 end-user workflow: it does not maintain Harness Alchemist itself or
+replace the generated repository's local maintenance skill.
+
+## Start Here
+
+1. Inspect the target directory before changing it.
+2. Read [references/compatibility.md](references/compatibility.md) before choosing paths or manifests.
+3. For a new project, run `harness-alchemist create --help` and use the CLI instead of recreating the structure manually.
+4. After creation, load `.agents/skills/develop-<name>/` in the generated project before maintaining its files.
+5. Run `harness-alchemist validate` and the generated package's `verify` script before reporting completion.
+
+## Create A Project
+
+Gather a lowercase kebab-case plugin name, description, npm package name, author, repository, and license. Then run:
+
+```bash
+harness-alchemist create /absolute/path/to/project \
+  --name my-plugin \
+  --description "What the plugin does" \
+  --package @scope/my-plugin \
+  --author "Example Team" \
+  --repository example/my-plugin
+```
+
+Use `bunx harness-alchemist create ...` or `npx harness-alchemist create ...` when the CLI is not installed. The CLI only writes to a missing or empty destination.
+
+## After Generation
+
+The generated `skills/<name>/SKILL.md` is the plugin's end-user workflow
+starter. The generated `.agents/skills/develop-<name>/` is its maintenance
+guide; use that local skill for file ownership, metadata, and harness changes.
+
+List supported template versions with:
+
+```bash
+harness-alchemist templates
+```
+
+## Verify
+
+```bash
+harness-alchemist validate /path/to/project
+cd /path/to/project
+npm install
+npm run verify
+npm pack --dry-run
+```
+
+Static validation is structural evidence, not proof that remote services or host-specific lifecycle events work.

package/skills/harness-alchemist/references/antigravity.md

@@ -0,0 +1,37 @@
+# Google Antigravity Plugins
+
+## Plugin Shape
+
+```text
+plugin.json
+skills/<name>/SKILL.md
+rules/<name>.md
+hooks.json
+mcp_config.json
+```
+
+Only `plugin.json` is required. The CLI manifest schema accepts a machine-readable name and optional description. Keep the root manifest separate from Claude and Codex manifests.
+
+Current Antigravity Agent Skills use the open Agent Skills directory format with nested `<name>/SKILL.md`. This is also the documented plugin skill shape.
+
+## Installation
+
+Antigravity 2 scans workspace plugins under `.agents/plugins/` or `_agents/plugins/`, and global plugins under `~/.gemini/config/plugins/`.
+
+Antigravity CLI stages installed plugins under `~/.gemini/antigravity-cli/plugins/<name>/` and supports:
+
+```bash
+agy plugin install /path/to/plugin
+agy plugin list
+agy plugin disable plugin-name
+agy plugin enable plugin-name
+agy plugin uninstall plugin-name
+```
+
+The CLI documentation also shows a legacy flat Markdown workspace-skill example. Prefer the nested Agent Skills shape because the current Antigravity Skills and plugin documentation both specify it.
+
+Official references:
+
+- https://antigravity.google/docs/plugins/
+- https://antigravity.google/docs/skills/
+- https://antigravity.google/docs/cli/plugins/

package/skills/harness-alchemist/references/claude-code.md

@@ -0,0 +1,51 @@
+# Claude Code Plugins
+
+## Required Shape
+
+For a manifest-backed plugin:
+
+```text
+.claude-plugin/plugin.json
+skills/<name>/SKILL.md
+```
+
+For repository installation, add `.claude-plugin/marketplace.json`. A one-plugin repository may use `"source": "./"`.
+
+Only `plugin.json` belongs inside `.claude-plugin/`. Components remain at the plugin root.
+
+## Supported Components
+
+- `skills/<name>/SKILL.md`; prefer this over legacy `commands/*.md`.
+- `agents/*.md`.
+- `hooks/hooks.json`.
+- `.mcp.json`.
+- `.lsp.json`.
+- `monitors/monitors.json`.
+- `bin/` for executables added to the Bash tool path.
+- Root `settings.json` for supported plugin defaults.
+
+Use `${CLAUDE_PLUGIN_ROOT}` for files within the copied plugin. Do not reference `../` paths outside the repository payload.
+
+## Development
+
+```bash
+claude --plugin-dir /absolute/path/to/plugin
+claude plugin validate /absolute/path/to/plugin --strict
+```
+
+Use `/reload-plugins` after component changes when supported.
+
+## Distribution
+
+```bash
+claude plugin marketplace add owner/repo
+claude plugin install plugin-name@marketplace-name
+```
+
+Marketplace installation copies plugins into a cache. Versioned manifests require a version bump for updates.
+
+Official references:
+
+- https://code.claude.com/docs/en/plugins
+- https://code.claude.com/docs/en/plugins-reference
+- https://code.claude.com/docs/en/plugin-marketplaces