@ex-machina/facets 0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ex-machina/facets",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "facets": "./src/cli.ts"
+  },
+  "scripts": {
+    "types": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "comment-json": "^4.2.5",
+    "js-yaml": "^4.1.0",
+    "zod": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/__tests__/e2e.test.ts

@@ -0,0 +1,129 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test"
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "path"
+import yaml from "js-yaml"
+import { listFacets } from "../discovery/list.ts"
+import { installFacet } from "../installation/install.ts"
+import { uninstallFacet } from "../installation/uninstall.ts"
+import { initProject } from "../cli/init.ts"
+
+let projectRoot: string
+
+beforeEach(async () => {
+  projectRoot = await mkdtemp(path.join(tmpdir(), "facets-e2e-"))
+})
+
+afterEach(async () => {
+  await rm(projectRoot, { recursive: true, force: true })
+})
+
+async function writeLocalFacet(
+  name: string,
+  manifest: Record<string, unknown>,
+  files?: Record<string, string>,
+) {
+  const dir = `${projectRoot}/.opencode/facets/${name}`
+  await Bun.$`mkdir -p ${dir}`
+  await Bun.write(`${dir}/facet.yaml`, yaml.dump(manifest))
+  for (const [relPath, content] of Object.entries(files ?? {})) {
+    const fullPath = `${dir}/${relPath}`
+    await Bun.$`mkdir -p ${path.dirname(fullPath)}`
+    await Bun.write(fullPath, content)
+  }
+}
+
+describe("End-to-end", () => {
+  test("init → list → install → verify resources → uninstall", async () => {
+    // 1. Init the project
+    await initProject(projectRoot)
+
+    // Verify opencode.jsonc was created with MCP server registered
+    const configText = await Bun.file(`${projectRoot}/.opencode/opencode.jsonc`).text()
+    expect(configText).toContain("facets-mcp")
+
+    // Verify facets.yaml was created
+    expect(await Bun.file(`${projectRoot}/.opencode/facets.yaml`).exists()).toBe(true)
+
+    // 2. Create a local facet
+    await writeLocalFacet(
+      "test-facet",
+      {
+        name: "test-facet",
+        version: "1.0.0",
+        description: "End-to-end test facet",
+        skills: ["e2e-skill"],
+        agents: {
+          "e2e-agent": {
+            description: "E2E test agent",
+            prompt: "prompts/e2e-agent.md",
+            platforms: {
+              opencode: { tools: { write: false } },
+            },
+          },
+        },
+        commands: {
+          "e2e-cmd": {
+            description: "E2E test command",
+            prompt: "prompts/e2e-cmd.md",
+          },
+        },
+      },
+      {
+        "skills/e2e-skill/SKILL.md": "# E2E Skill\nThis is a test skill.",
+        "prompts/e2e-agent.md": "You are an end-to-end test agent.",
+        "prompts/e2e-cmd.md": "Run the e2e test command.",
+      },
+    )
+
+    // 3. List — should show the facet as not installed
+    let list = await listFacets(projectRoot)
+    expect(list.facets).toHaveLength(1)
+    expect(list.facets[0]!.name).toBe("test-facet")
+    expect(list.facets[0]!.installed).toBe(false)
+
+    // 4. Install
+    const installResult = await installFacet("test-facet", projectRoot)
+    expect(installResult.success).toBe(true)
+    if (installResult.success) {
+      expect(installResult.resources).toHaveLength(3)
+    }
+
+    // 5. Verify resource files are present
+    expect(await Bun.file(`${projectRoot}/.opencode/skills/e2e-skill/SKILL.md`).exists()).toBe(true)
+    expect(await Bun.file(`${projectRoot}/.opencode/agents/e2e-agent.md`).exists()).toBe(true)
+    expect(await Bun.file(`${projectRoot}/.opencode/commands/e2e-cmd.md`).exists()).toBe(true)
+
+    // Verify agent file has assembled frontmatter
+    const agentContent = await Bun.file(`${projectRoot}/.opencode/agents/e2e-agent.md`).text()
+    expect(agentContent).toContain("description: E2E test agent")
+    expect(agentContent).toContain("You are an end-to-end test agent.")
+
+    // 6. List — should now show as installed
+    list = await listFacets(projectRoot)
+    expect(list.facets[0]!.installed).toBe(true)
+
+    // 7. Uninstall
+    const uninstallResult = await uninstallFacet("test-facet", projectRoot)
+    expect(uninstallResult.success).toBe(true)
+
+    // 8. Verify resources removed
+    expect(await Bun.file(`${projectRoot}/.opencode/skills/e2e-skill/SKILL.md`).exists()).toBe(false)
+    expect(await Bun.file(`${projectRoot}/.opencode/agents/e2e-agent.md`).exists()).toBe(false)
+    expect(await Bun.file(`${projectRoot}/.opencode/commands/e2e-cmd.md`).exists()).toBe(false)
+
+    // 9. List — should be back to not installed
+    list = await listFacets(projectRoot)
+    expect(list.facets[0]!.installed).toBe(false)
+  })
+
+  test("init is idempotent", async () => {
+    await initProject(projectRoot)
+    await initProject(projectRoot)
+
+    // MCP server should only be registered once
+    const configText = await Bun.file(`${projectRoot}/.opencode/opencode.jsonc`).text()
+    const matches = configText.match(/facets-mcp/g)
+    expect(matches).toHaveLength(1)
+  })
+})

package/src/cli/init.ts

@@ -0,0 +1,58 @@
+import { parse, stringify } from "comment-json"
+import { facetsYamlPath } from "../registry/files.ts"
+
+const OPENCODE_CONFIG_PATH = ".opencode/opencode.jsonc"
+
+const MCP_SERVER_CONFIG = {
+  type: "local",
+  command: ["bunx", "facets-mcp"],
+  enabled: true,
+} as const
+
+/**
+ * Initialize a project for facets:
+ * 1. Register the facets MCP server in .opencode/opencode.jsonc
+ * 2. Create facets.yaml if absent
+ */
+export async function initProject(projectRoot: string): Promise<void> {
+  const configPath = `${projectRoot}/${OPENCODE_CONFIG_PATH}`
+
+  // Ensure .opencode/ directory exists
+  await Bun.$`mkdir -p ${projectRoot}/.opencode`
+
+  // Read or create opencode.jsonc
+  let config: Record<string, unknown>
+  let configText: string
+
+  try {
+    configText = await Bun.file(configPath).text()
+    config = parse(configText) as Record<string, unknown>
+  } catch {
+    // Config doesn't exist — create a new one
+    config = {}
+    configText = "{}"
+  }
+
+  // Check if MCP server is already registered
+  const mcp = (config.mcp ?? {}) as Record<string, unknown>
+  if (mcp.facets) {
+    console.log("Project already configured for facets.")
+    return
+  }
+
+  // Register the facets MCP server
+  mcp.facets = MCP_SERVER_CONFIG
+  config.mcp = mcp
+
+  // Write back preserving comments
+  const newConfig = stringify(config, null, 2)
+  await Bun.write(configPath, newConfig + "\n")
+  console.log(`Registered facets MCP server in ${OPENCODE_CONFIG_PATH}`)
+
+  // Create facets.yaml if absent
+  const yamlPath = facetsYamlPath(projectRoot)
+  if (!(await Bun.file(yamlPath).exists())) {
+    await Bun.write(yamlPath, "# Facet dependencies for this project\nlocal: []\nremote: {}\n")
+    console.log("Created facets.yaml")
+  }
+}

package/src/cli.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env bun
+import { parseArgs } from "util"
+import { listFacets } from "./discovery/list.ts"
+import { cacheFacet } from "./discovery/cache.ts"
+import { clearCache } from "./discovery/clear.ts"
+import { installFacet } from "./installation/install.ts"
+import { uninstallFacet } from "./installation/uninstall.ts"
+
+const HELP = `Usage: facets <command> [options]
+
+Commands:
+  init                Set up project for facets
+  list                List all facets and their status
+  add <url>           Cache a remote facet by URL
+  install [name]      Install a facet's resources
+  remove <name>       Remove a facet
+  update [name]       Update cached remote facets
+  cache clear         Clear the global facet cache
+
+Options:
+  --help, -h          Show this help message
+  --version, -v       Show version`
+
+async function main() {
+  const args = process.argv.slice(2)
+
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    console.log(HELP)
+    process.exit(0)
+  }
+
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log("0.1.0")
+    process.exit(0)
+  }
+
+  const command = args[0]
+
+  switch (command) {
+    case "init":
+      await cmdInit()
+      break
+    case "list":
+      await cmdList()
+      break
+    case "add":
+      await cmdAdd(args[1])
+      break
+    case "install":
+      await cmdInstall(args[1])
+      break
+    case "remove":
+      await cmdRemove(args[1])
+      break
+    case "update":
+      await cmdUpdate(args[1])
+      break
+    case "cache":
+      if (args[1] === "clear") {
+        await cmdCacheClear()
+      } else {
+        console.error(`Unknown cache subcommand: ${args[1]}`)
+        console.error('Usage: facets cache clear')
+        process.exit(1)
+      }
+      break
+    default:
+      console.error(`Unknown command: ${command}`)
+      console.log(HELP)
+      process.exit(1)
+  }
+}
+
+async function cmdInit() {
+  const { initProject } = await import("./cli/init.ts")
+  await initProject(process.cwd())
+}
+
+async function cmdList() {
+  const projectRoot = process.cwd()
+  const result = await listFacets(projectRoot)
+
+  if (result.facets.length === 0) {
+    console.log("No facets declared.")
+    return
+  }
+
+  for (const facet of result.facets) {
+    const status = facet.installed ? "installed" : "not installed"
+    const version = facet.version ? `v${facet.version}` : ""
+    const source = facet.source === "local" ? "local" : "remote"
+    console.log(`  ${facet.name} ${version} (${source}) [${status}]`)
+    if (facet.description) {
+      console.log(`    ${facet.description}`)
+    }
+  }
+}
+
+async function cmdAdd(url: string | undefined) {
+  if (!url) {
+    console.error("Usage: facets add <url>")
+    process.exit(1)
+  }
+
+  const projectRoot = process.cwd()
+  const result = await cacheFacet(url, projectRoot)
+
+  if (result.success) {
+    console.log(`Cached: ${result.name} v${result.version}`)
+  } else {
+    console.error(`Failed to cache facet: ${result.error}`)
+    process.exit(1)
+  }
+}
+
+async function cmdInstall(name: string | undefined) {
+  const projectRoot = process.cwd()
+
+  if (!name) {
+    // Install all declared facets
+    const list = await listFacets(projectRoot)
+    for (const facet of list.facets) {
+      if (!facet.installed) {
+        const result = await installFacet(facet.name, projectRoot)
+        if (result.success) {
+          console.log(`Installed: ${facet.name}`)
+        } else {
+          console.error(`Failed to install ${facet.name}: ${result.reason}`)
+        }
+      }
+    }
+    return
+  }
+
+  const result = await installFacet(name, projectRoot)
+  if (result.success) {
+    console.log(`Installed: ${name}`)
+    for (const r of result.resources) {
+      console.log(`  ${r.type}: ${r.name}`)
+    }
+  } else {
+    console.error(`Failed to install ${name}: ${result.reason}`)
+    if (result.reason === "prereq" && "failure" in result) {
+      console.error(`  Command failed: ${result.failure.command}`)
+    }
+    process.exit(1)
+  }
+}
+
+async function cmdRemove(name: string | undefined) {
+  if (!name) {
+    console.error("Usage: facets remove <name>")
+    process.exit(1)
+  }
+
+  const projectRoot = process.cwd()
+  const result = await uninstallFacet(name, projectRoot)
+
+  if (result.success) {
+    console.log(`Removed: ${name}`)
+  } else {
+    console.error(`Failed to remove ${name}: ${result.reason}`)
+    process.exit(1)
+  }
+}
+
+async function cmdUpdate(name: string | undefined) {
+  const { updateFacet, updateAllFacets } = await import("./discovery/cache.ts")
+
+  if (name) {
+    const result = await updateFacet(name, process.cwd())
+    if (result.success) {
+      if (result.updated) {
+        console.log(`Updated: ${name} → v${result.version}`)
+      } else {
+        console.log(`${name}: already current (v${result.version})`)
+      }
+    } else {
+      console.error(`Failed to update ${name}: ${result.error}`)
+      process.exit(1)
+    }
+  } else {
+    const results = await updateAllFacets(process.cwd())
+    for (const result of results) {
+      if (result.success) {
+        if (result.updated) {
+          console.log(`Updated: ${result.name} → v${result.version}`)
+        } else {
+          console.log(`${result.name}: already current`)
+        }
+      } else {
+        console.error(`Failed to update ${result.name}: ${result.error}`)
+      }
+    }
+  }
+}
+
+async function cmdCacheClear() {
+  await clearCache()
+  console.log("Cache cleared.")
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/src/discovery/__tests__/list.test.ts

@@ -0,0 +1,114 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test"
+import { listFacets } from "../list.ts"
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "path"
+import yaml from "js-yaml"
+
+let projectRoot: string
+
+beforeEach(async () => {
+  projectRoot = await mkdtemp(path.join(tmpdir(), "facets-test-"))
+  await Bun.$`mkdir -p ${projectRoot}/.opencode/facets`
+})
+
+afterEach(async () => {
+  await rm(projectRoot, { recursive: true, force: true })
+})
+
+async function writeLocalFacet(name: string, manifest: Record<string, unknown>) {
+  const dir = `${projectRoot}/.opencode/facets/${name}`
+  await Bun.$`mkdir -p ${dir}`
+  await Bun.write(`${dir}/facet.yaml`, yaml.dump(manifest))
+}
+
+describe("listFacets", () => {
+  test("returns empty list when no facets exist", async () => {
+    const result = await listFacets(projectRoot)
+    expect(result.facets).toEqual([])
+  })
+
+  test("includes local facets", async () => {
+    await writeLocalFacet("test-facet", {
+      name: "test-facet",
+      version: "1.0.0",
+      description: "A test facet",
+      skills: ["my-skill"],
+    })
+
+    const result = await listFacets(projectRoot)
+    expect(result.facets).toHaveLength(1)
+    expect(result.facets[0]!.name).toBe("test-facet")
+    expect(result.facets[0]!.version).toBe("1.0.0")
+    expect(result.facets[0]!.source).toBe("local")
+    expect(result.facets[0]!.installed).toBe(false)
+  })
+
+  test("reports installed status correctly", async () => {
+    await writeLocalFacet("test-facet", {
+      name: "test-facet",
+      version: "1.0.0",
+      skills: ["my-skill"],
+    })
+
+    // Not installed yet
+    let result = await listFacets(projectRoot)
+    expect(result.facets[0]!.installed).toBe(false)
+
+    // Create the expected installed file
+    await Bun.$`mkdir -p ${projectRoot}/.opencode/skills/my-skill`
+    await Bun.write(`${projectRoot}/.opencode/skills/my-skill/SKILL.md`, "# Skill")
+
+    result = await listFacets(projectRoot)
+    expect(result.facets[0]!.installed).toBe(true)
+  })
+
+  test("includes requires as metadata", async () => {
+    await writeLocalFacet("test-facet", {
+      name: "test-facet",
+      version: "1.0.0",
+      requires: ["gh --version"],
+      skills: ["s"],
+    })
+
+    const result = await listFacets(projectRoot)
+    expect(result.facets[0]!.requires).toEqual(["gh --version"])
+  })
+
+  test("lists resource summaries", async () => {
+    await writeLocalFacet("test-facet", {
+      name: "test-facet",
+      version: "1.0.0",
+      skills: ["my-skill"],
+      agents: { "my-agent": { prompt: "prompts/a.md" } },
+      commands: { "my-cmd": { prompt: "prompts/c.md" } },
+      platforms: { opencode: { tools: ["my-tool"] } },
+    })
+
+    const result = await listFacets(projectRoot)
+    const resources = result.facets[0]!.resources
+    expect(resources).toContainEqual({ type: "skill", name: "my-skill" })
+    expect(resources).toContainEqual({ type: "agent", name: "my-agent" })
+    expect(resources).toContainEqual({ type: "command", name: "my-cmd" })
+    expect(resources).toContainEqual({ type: "tool", name: "my-tool" })
+  })
+
+  test("includes remote facets from facets.yaml", async () => {
+    const facetsYaml = {
+      remote: {
+        "remote-facet": {
+          url: "https://example.com/facet.yaml",
+          version: "2.0.0",
+        },
+      },
+    }
+    await Bun.write(`${projectRoot}/.opencode/facets.yaml`, yaml.dump(facetsYaml))
+
+    const result = await listFacets(projectRoot)
+    expect(result.facets).toHaveLength(1)
+    expect(result.facets[0]!.name).toBe("remote-facet")
+    expect(result.facets[0]!.source).toBe("remote")
+    // Not cached, so shows minimal info
+    expect(result.facets[0]!.version).toBe("2.0.0")
+  })
+})