@ex-machina/facets 0.1.0

package/src/discovery/cache.ts

@@ -0,0 +1,218 @@
+import path from "path"
+import yaml from "js-yaml"
+import { loadManifest } from "../registry/loader.ts"
+import { readFacetsYaml, writeFacetsYaml, readFacetsLock, writeFacetsLock } from "../registry/files.ts"
+import { resolvePromptPath, type FacetManifest } from "../registry/schemas.ts"
+
+const DEFAULT_CACHE_DIR = `${process.env.XDG_CACHE_HOME ?? `${process.env.HOME}/.cache`}/facets`
+
+/** Get the cache directory for a facet by name */
+export function getCacheDir(name: string): string {
+  return `${DEFAULT_CACHE_DIR}/${name}`
+}
+
+/** Get the root cache directory */
+export function getCacheRoot(): string {
+  return DEFAULT_CACHE_DIR
+}
+
+export interface CacheSuccess {
+  success: true
+  name: string
+  version: string
+}
+
+export interface CacheError {
+  success: false
+  error: string
+}
+
+export type CacheResult = CacheSuccess | CacheError
+
+/**
+ * Compute a SHA-256 integrity hash for a string.
+ */
+async function computeIntegrity(content: string): Promise<string> {
+  const hash = new Bun.CryptoHasher("sha256").update(content).digest("hex")
+  return `sha256-${hash}`
+}
+
+/**
+ * Fetch a remote URL and return its text content.
+ */
+async function fetchText(url: string): Promise<string> {
+  const response = await fetch(url)
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+  }
+  return response.text()
+}
+
+/**
+ * Resolve a relative URL against a base URL.
+ */
+function resolveUrl(base: string, relative: string): string {
+  const baseUrl = new URL(base)
+  // Navigate to parent directory of the base file
+  const basePath = baseUrl.pathname.replace(/\/[^/]*$/, "/")
+  const resolved = new URL(relative, `${baseUrl.origin}${basePath}`)
+  return resolved.href
+}
+
+/**
+ * Collect all resource file paths referenced by a manifest.
+ * Returns paths relative to the facet root directory.
+ */
+function collectResourcePaths(manifest: FacetManifest): string[] {
+  const paths: string[] = []
+
+  // Skills
+  for (const skill of manifest.skills ?? []) {
+    paths.push(`skills/${skill}/SKILL.md`)
+  }
+
+  // Agent prompts
+  for (const agent of Object.values(manifest.agents ?? {})) {
+    const promptPath = resolvePromptPath(agent.prompt)
+    if (promptPath) paths.push(promptPath)
+  }
+
+  // Command prompts
+  for (const command of Object.values(manifest.commands ?? {})) {
+    const promptPath = resolvePromptPath(command.prompt)
+    if (promptPath) paths.push(promptPath)
+  }
+
+  // Platform-specific tools
+  for (const tool of manifest.platforms?.opencode?.tools ?? []) {
+    paths.push(`opencode/tools/${tool}.ts`)
+  }
+
+  return paths
+}
+
+/**
+ * Cache a remote facet by URL. Fetches the manifest and all referenced
+ * resources, stores them in the global cache, and records the dependency
+ * in the project's facets.yaml and facets.lock.
+ */
+export async function cacheFacet(url: string, projectRoot: string): Promise<CacheResult> {
+  // Fetch the manifest
+  let manifestText: string
+  try {
+    manifestText = await fetchText(url)
+  } catch (err) {
+    return { success: false, error: `Failed to fetch manifest: ${err}` }
+  }
+
+  // Parse and validate
+  let parsed: unknown
+  try {
+    parsed = yaml.load(manifestText)
+  } catch (err) {
+    return { success: false, error: `Invalid YAML at ${url}: ${err}` }
+  }
+
+  const { FacetManifestSchema } = await import("../registry/schemas.ts")
+  const validation = FacetManifestSchema.safeParse(parsed)
+  if (!validation.success) {
+    const issues = validation.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+    return { success: false, error: `Invalid manifest: ${issues}` }
+  }
+
+  const manifest = validation.data
+  const cacheDir = getCacheDir(manifest.name)
+
+  // Write the manifest
+  await Bun.$`mkdir -p ${cacheDir}`
+  await Bun.write(`${cacheDir}/facet.yaml`, manifestText)
+
+  // Fetch and cache all referenced resource files
+  const resourcePaths = collectResourcePaths(manifest)
+  for (const relPath of resourcePaths) {
+    const resourceUrl = resolveUrl(url, relPath)
+    try {
+      const content = await fetchText(resourceUrl)
+      const destPath = `${cacheDir}/${relPath}`
+      await Bun.$`mkdir -p ${path.dirname(destPath)}`
+      await Bun.write(destPath, content)
+    } catch (err) {
+      return { success: false, error: `Failed to fetch resource ${relPath}: ${err}` }
+    }
+  }
+
+  // Update facets.yaml
+  const facetsYaml = await readFacetsYaml(projectRoot)
+  if (!facetsYaml.remote) facetsYaml.remote = {}
+  facetsYaml.remote[manifest.name] = {
+    url,
+    version: manifest.version,
+  }
+  await writeFacetsYaml(projectRoot, facetsYaml)
+
+  // Update facets.lock
+  const lock = await readFacetsLock(projectRoot)
+  if (!lock.remote) lock.remote = {}
+  lock.remote[manifest.name] = {
+    url,
+    version: manifest.version,
+    integrity: await computeIntegrity(manifestText),
+  }
+  await writeFacetsLock(projectRoot, lock)
+
+  return { success: true, name: manifest.name, version: manifest.version }
+}
+
+export interface UpdateSuccess {
+  success: true
+  name: string
+  version: string
+  updated: boolean
+}
+
+export interface UpdateError {
+  success: false
+  name: string
+  error: string
+}
+
+export type UpdateResult = UpdateSuccess | UpdateError
+
+/**
+ * Re-fetch a single cached remote facet and update if newer.
+ */
+export async function updateFacet(name: string, projectRoot: string): Promise<UpdateResult> {
+  const facetsYaml = await readFacetsYaml(projectRoot)
+  const entry = facetsYaml.remote?.[name]
+  if (!entry) {
+    return { success: false, name, error: `No remote facet named "${name}" declared` }
+  }
+
+  const lock = await readFacetsLock(projectRoot)
+  const lockEntry = lock.remote?.[name]
+
+  // Re-fetch
+  const result = await cacheFacet(entry.url, projectRoot)
+  if (!result.success) {
+    return { success: false, name, error: result.error }
+  }
+
+  // Check if the version changed
+  const updated = lockEntry ? lockEntry.version !== result.version : true
+
+  return { success: true, name, version: result.version, updated }
+}
+
+/**
+ * Update all remote facets declared in facets.yaml.
+ */
+export async function updateAllFacets(projectRoot: string): Promise<UpdateResult[]> {
+  const facetsYaml = await readFacetsYaml(projectRoot)
+  const results: UpdateResult[] = []
+
+  for (const name of Object.keys(facetsYaml.remote ?? {})) {
+    results.push(await updateFacet(name, projectRoot))
+  }
+
+  return results
+}

package/src/discovery/clear.ts

@@ -0,0 +1,15 @@
+import { getCacheRoot } from "./cache.ts"
+import { rm } from "node:fs/promises"
+
+/**
+ * Remove the entire global facet cache directory.
+ * Does not affect local facets or installed resources.
+ */
+export async function clearCache(): Promise<void> {
+  const cacheRoot = getCacheRoot()
+  try {
+    await rm(cacheRoot, { recursive: true, force: true })
+  } catch {
+    // Cache dir doesn't exist — that's fine
+  }
+}

package/src/discovery/list.ts

@@ -0,0 +1,129 @@
+import { loadManifest } from "../registry/loader.ts"
+import { readFacetsYaml, localFacetsDir } from "../registry/files.ts"
+import { normalizeRequires, type FacetManifest } from "../registry/schemas.ts"
+import { getCacheDir } from "./cache.ts"
+import { isInstalled } from "../installation/status.ts"
+
+export interface FacetEntry {
+  name: string
+  version: string
+  description?: string
+  source: "local" | "remote"
+  installed: boolean
+  requires: string[]
+  resources: ResourceSummary[]
+}
+
+export interface ResourceSummary {
+  type: "skill" | "agent" | "command" | "tool"
+  name: string
+}
+
+export interface ListResult {
+  facets: FacetEntry[]
+  errors?: string[]
+}
+
+function extractResources(manifest: FacetManifest): ResourceSummary[] {
+  const resources: ResourceSummary[] = []
+
+  for (const skill of manifest.skills ?? []) {
+    resources.push({ type: "skill", name: skill })
+  }
+  for (const name of Object.keys(manifest.agents ?? {})) {
+    resources.push({ type: "agent", name })
+  }
+  for (const name of Object.keys(manifest.commands ?? {})) {
+    resources.push({ type: "command", name })
+  }
+  for (const tool of manifest.platforms?.opencode?.tools ?? []) {
+    resources.push({ type: "tool", name: tool })
+  }
+
+  return resources
+}
+
+/**
+ * List all facets declared by the project — local facets and remote facets
+ * from facets.yaml. Read-only: no network, no command execution.
+ */
+export async function listFacets(projectRoot: string): Promise<ListResult> {
+  const facets: FacetEntry[] = []
+  const errors: string[] = []
+  const facetsYaml = await readFacetsYaml(projectRoot)
+
+  // Scan local facets
+  const localDir = localFacetsDir(projectRoot)
+  try {
+    const entries: string[] = []
+    for await (const entry of new Bun.Glob("*/facet.yaml").scan(localDir)) {
+      entries.push(entry)
+    }
+
+    for (const entry of entries) {
+      const facetDir = `${localDir}/${entry.replace(/\/facet\.yaml$/, "")}`
+      const manifestPath = `${localDir}/${entry}`
+      const result = await loadManifest(manifestPath)
+      if (!result.success) {
+        errors.push(`Local facet at ${facetDir}: ${result.error}`)
+        continue
+      }
+      const manifest = result.manifest
+      facets.push({
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description,
+        source: "local",
+        installed: await isInstalled(manifest, projectRoot),
+        requires: normalizeRequires(manifest.requires),
+        resources: extractResources(manifest),
+      })
+    }
+  } catch {
+    // No local facets dir — fine
+  }
+
+  // Scan remote facets declared in facets.yaml
+  for (const [name, entry] of Object.entries(facetsYaml.remote ?? {})) {
+    const cacheDir = getCacheDir(name)
+    const manifestPath = `${cacheDir}/facet.yaml`
+    const result = await loadManifest(manifestPath)
+    if (!result.success) {
+      // Cached manifest not available — show minimal info
+      facets.push({
+        name,
+        version: entry.version ?? "unknown",
+        source: "remote",
+        installed: false,
+        requires: [],
+        resources: [],
+      })
+      continue
+    }
+    const manifest = result.manifest
+    facets.push({
+      name: manifest.name,
+      version: manifest.version,
+      description: manifest.description,
+      source: "remote",
+      installed: await isInstalled(manifest, projectRoot),
+      requires: normalizeRequires(manifest.requires),
+      resources: extractResources(manifest),
+    })
+  }
+
+  // Include local facets declared in facets.yaml that weren't already found
+  for (const name of facetsYaml.local ?? []) {
+    if (facets.some((f) => f.name === name)) continue
+    facets.push({
+      name,
+      version: "unknown",
+      source: "local",
+      installed: false,
+      requires: [],
+      resources: [],
+    })
+  }
+
+  return { facets, ...(errors.length > 0 && { errors }) }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Registry — schemas and loaders
+export {
+  FacetManifestSchema,
+  FacetsYamlSchema,
+  FacetsLockSchema,
+  type FacetManifest,
+  type FacetsYaml,
+  type FacetsLock,
+} from "./registry/schemas.ts"
+export { loadManifest } from "./registry/loader.ts"
+export { readFacetsYaml, writeFacetsYaml, readFacetsLock, writeFacetsLock } from "./registry/files.ts"
+
+// Discovery — list, cache, clear
+export { listFacets, type FacetEntry, type ListResult } from "./discovery/list.ts"
+export { cacheFacet, updateFacet, updateAllFacets, type CacheResult, type UpdateResult } from "./discovery/cache.ts"
+export { clearCache } from "./discovery/clear.ts"
+
+// Installation — install, uninstall, prerequisites
+export {
+  installFacet,
+  type InstallResult,
+  type InstallSuccess,
+  type InstallNotFound,
+  type InstallPrereqFailure,
+  type InstallCopyFailure,
+} from "./installation/install.ts"
+export { uninstallFacet, type UninstallResult } from "./installation/uninstall.ts"

package/src/installation/__tests__/install.test.ts

@@ -0,0 +1,210 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test"
+import { installFacet } from "../install.ts"
+import { uninstallFacet } from "../uninstall.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>,
+  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("installFacet", () => {
+  test("installs local facet with skill", async () => {
+    await writeLocalFacet(
+      "test-facet",
+      {
+        name: "test-facet",
+        version: "1.0.0",
+        skills: ["my-skill"],
+      },
+      { "skills/my-skill/SKILL.md": "# My Skill\nDoes things." },
+    )
+
+    const result = await installFacet("test-facet", projectRoot)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.resources).toContainEqual({ name: "my-skill", type: "skill" })
+    }
+
+    // Verify file exists
+    const installed = await Bun.file(`${projectRoot}/.opencode/skills/my-skill/SKILL.md`).exists()
+    expect(installed).toBe(true)
+  })
+
+  test("installs agent with assembled frontmatter", async () => {
+    await writeLocalFacet(
+      "test-facet",
+      {
+        name: "test-facet",
+        version: "1.0.0",
+        agents: {
+          "my-agent": {
+            description: "Does a thing",
+            prompt: "prompts/my-agent.md",
+            platforms: {
+              opencode: { tools: { write: false } },
+            },
+          },
+        },
+      },
+      { "prompts/my-agent.md": "You are a helpful agent." },
+    )
+
+    const result = await installFacet("test-facet", projectRoot)
+    expect(result.success).toBe(true)
+
+    const content = await Bun.file(`${projectRoot}/.opencode/agents/my-agent.md`).text()
+    expect(content).toContain("---")
+    expect(content).toContain("description: Does a thing")
+    expect(content).toContain("You are a helpful agent.")
+  })
+
+  test("installs command with assembled frontmatter", async () => {
+    await writeLocalFacet(
+      "test-facet",
+      {
+        name: "test-facet",
+        version: "1.0.0",
+        commands: {
+          "my-command": {
+            description: "What it does",
+            prompt: "prompts/my-command.md",
+          },
+        },
+      },
+      { "prompts/my-command.md": "Run this command." },
+    )
+
+    const result = await installFacet("test-facet", projectRoot)
+    expect(result.success).toBe(true)
+
+    const content = await Bun.file(`${projectRoot}/.opencode/commands/my-command.md`).text()
+    expect(content).toContain("description: What it does")
+    expect(content).toContain("Run this command.")
+  })
+
+  test("installs platform tools", async () => {
+    await writeLocalFacet(
+      "test-facet",
+      {
+        name: "test-facet",
+        version: "1.0.0",
+        platforms: {
+          opencode: { tools: ["my-tool"] },
+        },
+      },
+      { "opencode/tools/my-tool.ts": 'export default "tool"' },
+    )
+
+    const result = await installFacet("test-facet", projectRoot)
+    expect(result.success).toBe(true)
+
+    const installed = await Bun.file(`${projectRoot}/.opencode/tools/my-tool.ts`).exists()
+    expect(installed).toBe(true)
+  })
+
+  test("returns not_found for unknown facet", async () => {
+    const result = await installFacet("nonexistent", projectRoot)
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.reason).toBe("not_found")
+    }
+  })
+
+  test("runs prereq checks and fails on bad command", async () => {
+    await writeLocalFacet(
+      "test-facet",
+      {
+        name: "test-facet",
+        version: "1.0.0",
+        requires: ["false"],
+        skills: ["s"],
+      },
+      { "skills/s/SKILL.md": "# S" },
+    )
+
+    const result = await installFacet("test-facet", projectRoot, {
+      skipPrereqApproval: true,
+    })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.reason).toBe("prereq")
+    }
+  })
+
+  test("user declining prereqs cancels install", async () => {
+    await writeLocalFacet(
+      "test-facet",
+      {
+        name: "test-facet",
+        version: "1.0.0",
+        requires: ["true"],
+        skills: ["s"],
+      },
+      { "skills/s/SKILL.md": "# S" },
+    )
+
+    const result = await installFacet("test-facet", projectRoot, {
+      onPrereqApproval: async () => false,
+    })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.reason).toBe("prereq")
+    }
+  })
+})
+
+describe("uninstallFacet", () => {
+  test("removes installed resources", async () => {
+    await writeLocalFacet(
+      "test-facet",
+      {
+        name: "test-facet",
+        version: "1.0.0",
+        skills: ["my-skill"],
+      },
+      { "skills/my-skill/SKILL.md": "# My Skill" },
+    )
+
+    // Install first
+    await installFacet("test-facet", projectRoot)
+    expect(await Bun.file(`${projectRoot}/.opencode/skills/my-skill/SKILL.md`).exists()).toBe(true)
+
+    // Uninstall
+    const result = await uninstallFacet("test-facet", projectRoot)
+    expect(result.success).toBe(true)
+    expect(await Bun.file(`${projectRoot}/.opencode/skills/my-skill/SKILL.md`).exists()).toBe(false)
+  })
+
+  test("returns not_found for unknown facet", async () => {
+    const result = await uninstallFacet("nonexistent", projectRoot)
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.reason).toBe("not_found")
+    }
+  })
+})