@ex-machina/facets 0.1.0

package/src/installation/install.ts

@@ -0,0 +1,232 @@
+import path from "path"
+import yaml from "js-yaml"
+import { loadManifest } from "../registry/loader.ts"
+import { localFacetsDir } from "../registry/files.ts"
+import { getCacheDir } from "../discovery/cache.ts"
+import { resolvePromptPath, normalizeRequires, type FacetManifest } from "../registry/schemas.ts"
+
+// --- Prerequisite checking ---
+
+const PREREQ_CONFIRMED_DIR = `${process.env.XDG_STATE_HOME ?? `${process.env.HOME}/.local/state`}/facets/prereqs`
+
+interface PrereqSuccess {
+  success: true
+}
+
+interface PrereqFailure {
+  success: false
+  command: string
+  exitCode: number
+  output: string
+}
+
+type PrereqResult = PrereqSuccess | PrereqFailure
+
+async function isPrereqConfirmed(facetName: string): Promise<boolean> {
+  return Bun.file(`${PREREQ_CONFIRMED_DIR}/${facetName}`).exists()
+}
+
+async function markPrereqConfirmed(facetName: string): Promise<void> {
+  await Bun.$`mkdir -p ${PREREQ_CONFIRMED_DIR}`
+  await Bun.write(`${PREREQ_CONFIRMED_DIR}/${facetName}`, new Date().toISOString())
+}
+
+async function runPrereqChecks(commands: string[]): Promise<PrereqResult> {
+  for (const command of commands) {
+    const result = await Bun.$`${{ raw: command }}`.nothrow().quiet()
+    if (result.exitCode !== 0) {
+      return {
+        success: false,
+        command,
+        exitCode: result.exitCode,
+        output: (result.stderr.toString() + result.stdout.toString()).trim(),
+      }
+    }
+  }
+  return { success: true }
+}
+
+// --- Agent/Command frontmatter assembly ---
+
+interface AgentFrontmatter {
+  description?: string
+  tools?: Record<string, boolean> | string[]
+  [key: string]: unknown
+}
+
+function assembleAgentFile(promptBody: string, descriptor: NonNullable<FacetManifest["agents"]>[string]): string {
+  const fm: AgentFrontmatter = {}
+  if (descriptor.description) fm.description = descriptor.description
+  const opencode = descriptor.platforms?.opencode
+  if (opencode?.tools) fm.tools = opencode.tools
+
+  const frontmatter = yaml.dump(fm, { lineWidth: -1, noRefs: true }).trim()
+  return `---\n${frontmatter}\n---\n\n${promptBody}`
+}
+
+function assembleCommandFile(promptBody: string, descriptor: NonNullable<FacetManifest["commands"]>[string]): string {
+  const fm: Record<string, unknown> = {}
+  if (descriptor.description) fm.description = descriptor.description
+
+  const frontmatter = yaml.dump(fm, { lineWidth: -1, noRefs: true }).trim()
+  return `---\n${frontmatter}\n---\n\n${promptBody}`
+}
+
+// --- Result types ---
+
+export interface InstallSuccess {
+  success: true
+  facet: string
+  resources: { name: string; type: string }[]
+}
+
+export interface InstallNotFound {
+  success: false
+  facet: string
+  reason: "not_found"
+}
+
+export interface InstallPrereqFailure {
+  success: false
+  facet: string
+  reason: "prereq"
+  failure: { command: string; exitCode: number; output: string }
+}
+
+export interface InstallCopyFailure {
+  success: false
+  facet: string
+  reason: "copy"
+  error: string
+}
+
+export type InstallResult = InstallSuccess | InstallNotFound | InstallPrereqFailure | InstallCopyFailure
+
+// --- Options ---
+
+export interface InstallOptions {
+  /** If true, skip interactive prereq approval (for programmatic use) */
+  skipPrereqApproval?: boolean
+  /** If true, force re-run prereq checks even if already confirmed */
+  forcePrereqCheck?: boolean
+  /** Callback to ask user for prereq approval. Returns true if approved. */
+  onPrereqApproval?: (commands: string[]) => Promise<boolean>
+}
+
+/**
+ * Resolve the facet directory — checks local first, then cache.
+ */
+async function resolveFacetDir(name: string, projectRoot: string): Promise<string | null> {
+  const localDir = `${localFacetsDir(projectRoot)}/${name}`
+  const localManifest = `${localDir}/facet.yaml`
+  if (await Bun.file(localManifest).exists()) return localDir
+
+  const cacheDir = getCacheDir(name)
+  const cacheManifest = `${cacheDir}/facet.yaml`
+  if (await Bun.file(cacheManifest).exists()) return cacheDir
+
+  return null
+}
+
+/**
+ * Install a named facet, copying its resources to the active OpenCode directories.
+ */
+export async function installFacet(
+  name: string,
+  projectRoot: string,
+  options: InstallOptions = {},
+): Promise<InstallResult> {
+  const facetDir = await resolveFacetDir(name, projectRoot)
+  if (!facetDir) {
+    return { success: false, facet: name, reason: "not_found" }
+  }
+
+  const manifestResult = await loadManifest(`${facetDir}/facet.yaml`)
+  if (!manifestResult.success) {
+    return { success: false, facet: name, reason: "not_found" }
+  }
+
+  const manifest = manifestResult.manifest
+  const base = `${projectRoot}/.opencode`
+
+  // Prerequisites
+  const requires = normalizeRequires(manifest.requires)
+  if (requires.length > 0) {
+    const alreadyConfirmed = !options.forcePrereqCheck && (await isPrereqConfirmed(name))
+
+    if (!alreadyConfirmed) {
+      // Ask for approval if handler is provided
+      if (options.onPrereqApproval) {
+        const approved = await options.onPrereqApproval(requires)
+        if (!approved) {
+          return {
+            success: false,
+            facet: name,
+            reason: "prereq",
+            failure: { command: "(user declined)", exitCode: -1, output: "Prerequisite approval declined" },
+          }
+        }
+      }
+
+      // Run checks
+      const prereqResult = await runPrereqChecks(requires)
+      if (!prereqResult.success) {
+        return { success: false, facet: name, reason: "prereq", failure: prereqResult }
+      }
+
+      // Mark confirmed
+      await markPrereqConfirmed(name)
+    }
+  }
+
+  // Install resources
+  const installed: { name: string; type: string }[] = []
+
+  try {
+    // Skills — copy entire directory
+    for (const skill of manifest.skills ?? []) {
+      const src = `${facetDir}/skills/${skill}/SKILL.md`
+      const dst = `${base}/skills/${skill}/SKILL.md`
+      await Bun.$`mkdir -p ${path.dirname(dst)}`
+      await Bun.$`cp ${src} ${dst}`
+      installed.push({ name: skill, type: "skill" })
+    }
+
+    // Agents — read prompt body, assemble with frontmatter
+    for (const [agentName, descriptor] of Object.entries(manifest.agents ?? {})) {
+      const promptPath = resolvePromptPath(descriptor.prompt)
+      if (!promptPath) continue
+      const promptBody = await Bun.file(`${facetDir}/${promptPath}`).text()
+      const assembled = assembleAgentFile(promptBody, descriptor)
+      const dst = `${base}/agents/${agentName}.md`
+      await Bun.$`mkdir -p ${path.dirname(dst)}`
+      await Bun.write(dst, assembled)
+      installed.push({ name: agentName, type: "agent" })
+    }
+
+    // Commands — read prompt body, assemble with frontmatter
+    for (const [cmdName, descriptor] of Object.entries(manifest.commands ?? {})) {
+      const promptPath = resolvePromptPath(descriptor.prompt)
+      if (!promptPath) continue
+      const promptBody = await Bun.file(`${facetDir}/${promptPath}`).text()
+      const assembled = assembleCommandFile(promptBody, descriptor)
+      const dst = `${base}/commands/${cmdName}.md`
+      await Bun.$`mkdir -p ${path.dirname(dst)}`
+      await Bun.write(dst, assembled)
+      installed.push({ name: cmdName, type: "command" })
+    }
+
+    // Platform tools — copy directly
+    for (const tool of manifest.platforms?.opencode?.tools ?? []) {
+      const src = `${facetDir}/opencode/tools/${tool}.ts`
+      const dst = `${base}/tools/${tool}.ts`
+      await Bun.$`mkdir -p ${path.dirname(dst)}`
+      await Bun.$`cp ${src} ${dst}`
+      installed.push({ name: tool, type: "tool" })
+    }
+  } catch (err) {
+    return { success: false, facet: name, reason: "copy", error: String(err) }
+  }
+
+  return { success: true, facet: name, resources: installed }
+}

package/src/installation/status.ts

@@ -0,0 +1,42 @@
+import type { FacetManifest } from "../registry/schemas.ts"
+
+/**
+ * Check whether a facet's resources are currently installed by
+ * verifying that expected destination files exist.
+ */
+export async function isInstalled(manifest: FacetManifest, projectRoot: string): Promise<boolean> {
+  const base = `${projectRoot}/.opencode`
+
+  // Check skills
+  for (const skill of manifest.skills ?? []) {
+    const exists = await Bun.file(`${base}/skills/${skill}/SKILL.md`).exists()
+    if (!exists) return false
+  }
+
+  // Check agents
+  for (const name of Object.keys(manifest.agents ?? {})) {
+    const exists = await Bun.file(`${base}/agents/${name}.md`).exists()
+    if (!exists) return false
+  }
+
+  // Check commands
+  for (const name of Object.keys(manifest.commands ?? {})) {
+    const exists = await Bun.file(`${base}/commands/${name}.md`).exists()
+    if (!exists) return false
+  }
+
+  // Check platform tools
+  for (const tool of manifest.platforms?.opencode?.tools ?? []) {
+    const exists = await Bun.file(`${base}/tools/${tool}.ts`).exists()
+    if (!exists) return false
+  }
+
+  // At least one resource must exist for a facet to be considered installed
+  const hasResources =
+    (manifest.skills?.length ?? 0) > 0 ||
+    Object.keys(manifest.agents ?? {}).length > 0 ||
+    Object.keys(manifest.commands ?? {}).length > 0 ||
+    (manifest.platforms?.opencode?.tools?.length ?? 0) > 0
+
+  return hasResources
+}

package/src/installation/uninstall.ts

@@ -0,0 +1,116 @@
+import { rm } from "node:fs/promises"
+import { loadManifest } from "../registry/loader.ts"
+import { localFacetsDir, readFacetsYaml, writeFacetsYaml } from "../registry/files.ts"
+import { getCacheDir } from "../discovery/cache.ts"
+
+export interface UninstallSuccess {
+  success: true
+  facet: string
+  removed: { name: string; type: string }[]
+}
+
+export interface UninstallNotFound {
+  success: false
+  facet: string
+  reason: "not_found"
+}
+
+export interface UninstallError {
+  success: false
+  facet: string
+  reason: "error"
+  error: string
+}
+
+export type UninstallResult = UninstallSuccess | UninstallNotFound | UninstallError
+
+/**
+ * Uninstall a facet: remove its installed resource files and remove
+ * it from facets.yaml.
+ */
+export async function uninstallFacet(name: string, projectRoot: string): Promise<UninstallResult> {
+  // Find the manifest (local or cached) to know what to remove
+  const localDir = `${localFacetsDir(projectRoot)}/${name}`
+  const cacheDir = getCacheDir(name)
+
+  let manifestPath: string | null = null
+  if (await Bun.file(`${localDir}/facet.yaml`).exists()) {
+    manifestPath = `${localDir}/facet.yaml`
+  } else if (await Bun.file(`${cacheDir}/facet.yaml`).exists()) {
+    manifestPath = `${cacheDir}/facet.yaml`
+  }
+
+  if (!manifestPath) {
+    return { success: false, facet: name, reason: "not_found" }
+  }
+
+  const manifestResult = await loadManifest(manifestPath)
+  if (!manifestResult.success) {
+    return { success: false, facet: name, reason: "error", error: manifestResult.error }
+  }
+
+  const manifest = manifestResult.manifest
+  const base = `${projectRoot}/.opencode`
+  const removed: { name: string; type: string }[] = []
+
+  try {
+    // Remove skills
+    for (const skill of manifest.skills ?? []) {
+      const skillDir = `${base}/skills/${skill}`
+      try {
+        await rm(skillDir, { recursive: true, force: true })
+        removed.push({ name: skill, type: "skill" })
+      } catch {
+        // Already gone
+      }
+    }
+
+    // Remove agents
+    for (const agentName of Object.keys(manifest.agents ?? {})) {
+      const agentFile = `${base}/agents/${agentName}.md`
+      try {
+        await rm(agentFile, { force: true })
+        removed.push({ name: agentName, type: "agent" })
+      } catch {
+        // Already gone
+      }
+    }
+
+    // Remove commands
+    for (const cmdName of Object.keys(manifest.commands ?? {})) {
+      const cmdFile = `${base}/commands/${cmdName}.md`
+      try {
+        await rm(cmdFile, { force: true })
+        removed.push({ name: cmdName, type: "command" })
+      } catch {
+        // Already gone
+      }
+    }
+
+    // Remove platform tools
+    for (const tool of manifest.platforms?.opencode?.tools ?? []) {
+      const toolFile = `${base}/tools/${tool}.ts`
+      try {
+        await rm(toolFile, { force: true })
+        removed.push({ name: tool, type: "tool" })
+      } catch {
+        // Already gone
+      }
+    }
+  } catch (err) {
+    return { success: false, facet: name, reason: "error", error: String(err) }
+  }
+
+  // Remove from facets.yaml
+  const facetsYaml = await readFacetsYaml(projectRoot)
+  if (facetsYaml.remote?.[name]) {
+    delete facetsYaml.remote[name]
+    await writeFacetsYaml(projectRoot, facetsYaml)
+  }
+  if (facetsYaml.local?.includes(name)) {
+    facetsYaml.local = facetsYaml.local.filter((n) => n !== name)
+    await writeFacetsYaml(projectRoot, facetsYaml)
+  }
+
+  return { success: true, facet: name, removed }
+}

package/src/registry/__tests__/loader.test.ts

@@ -0,0 +1,67 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test"
+import { loadManifest } from "../loader.ts"
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "path"
+import yaml from "js-yaml"
+
+let tempDir: string
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(path.join(tmpdir(), "facets-test-"))
+})
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true })
+})
+
+describe("loadManifest", () => {
+  test("loads valid manifest", async () => {
+    const manifest = { name: "test-facet", version: "1.0.0", description: "A test" }
+    await Bun.write(`${tempDir}/facet.yaml`, yaml.dump(manifest))
+
+    const result = await loadManifest(`${tempDir}/facet.yaml`)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.manifest.name).toBe("test-facet")
+      expect(result.manifest.version).toBe("1.0.0")
+      expect(result.manifest.description).toBe("A test")
+    }
+  })
+
+  test("returns error for missing file", async () => {
+    const result = await loadManifest(`${tempDir}/nonexistent.yaml`)
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.error).toContain("Cannot read manifest")
+    }
+  })
+
+  test("returns error for invalid YAML", async () => {
+    await Bun.write(`${tempDir}/facet.yaml`, ":\n  :\n    - [invalid\n")
+
+    const result = await loadManifest(`${tempDir}/facet.yaml`)
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.error).toMatch(/Invalid (YAML|manifest)/)
+    }
+  })
+
+  test("returns error for missing required fields", async () => {
+    await Bun.write(`${tempDir}/facet.yaml`, yaml.dump({ description: "no name or version" }))
+
+    const result = await loadManifest(`${tempDir}/facet.yaml`)
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.error).toContain("Invalid manifest")
+    }
+  })
+
+  test("tolerates unrecognized fields", async () => {
+    const manifest = { name: "test", version: "1.0.0", customField: "hello" }
+    await Bun.write(`${tempDir}/facet.yaml`, yaml.dump(manifest))
+
+    const result = await loadManifest(`${tempDir}/facet.yaml`)
+    expect(result.success).toBe(true)
+  })
+})

package/src/registry/__tests__/schemas.test.ts

@@ -0,0 +1,206 @@
+import { test, expect, describe } from "bun:test"
+import { FacetManifestSchema, FacetsYamlSchema, FacetsLockSchema, normalizeRequires, resolvePromptPath } from "../schemas.ts"
+
+describe("FacetManifestSchema", () => {
+  test("accepts valid minimal manifest", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "my-facet",
+      version: "1.0.0",
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts full manifest with all fields", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "my-facet",
+      version: "1.0.0",
+      description: "A test facet",
+      author: "Test <test@example.com>",
+      requires: ["gh --version", "jq --version"],
+      skills: ["my-skill"],
+      agents: {
+        "my-agent": {
+          description: "Does a thing",
+          prompt: "prompts/my-agent.md",
+          platforms: {
+            opencode: { tools: { write: false } },
+          },
+        },
+      },
+      commands: {
+        "my-command": {
+          description: "What it does",
+          prompt: { file: "prompts/my-command.md" },
+        },
+      },
+      platforms: {
+        opencode: {
+          tools: ["my-tool"],
+        },
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("rejects manifest without name", () => {
+    const result = FacetManifestSchema.safeParse({ version: "1.0.0" })
+    expect(result.success).toBe(false)
+  })
+
+  test("rejects manifest without version", () => {
+    const result = FacetManifestSchema.safeParse({ name: "test" })
+    expect(result.success).toBe(false)
+  })
+
+  test("tolerates unrecognized fields", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "my-facet",
+      version: "1.0.0",
+      unknownField: "value",
+      anotherField: 42,
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts requires as string", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "my-facet",
+      version: "1.0.0",
+      requires: "gh --version",
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts requires as array", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "my-facet",
+      version: "1.0.0",
+      requires: ["gh --version", "jq --version"],
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts prompt as string", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "test",
+      version: "1.0.0",
+      agents: {
+        agent1: { prompt: "prompts/agent1.md" },
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts prompt as object with file", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "test",
+      version: "1.0.0",
+      agents: {
+        agent1: { prompt: { file: "prompts/agent1.md" } },
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts prompt as object with url", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "test",
+      version: "1.0.0",
+      agents: {
+        agent1: { prompt: { url: "https://example.com/prompt" } },
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts agent with array-style tools", () => {
+    const result = FacetManifestSchema.safeParse({
+      name: "test",
+      version: "1.0.0",
+      agents: {
+        agent1: {
+          prompt: "prompts/a.md",
+          platforms: {
+            "claude-code": { tools: ["Read", "Edit", "Bash"] },
+          },
+        },
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+})
+
+describe("FacetsYamlSchema", () => {
+  test("accepts valid dependency file", () => {
+    const result = FacetsYamlSchema.safeParse({
+      local: ["my-local-facet"],
+      remote: {
+        viper: {
+          url: "https://example.com/facets/viper/facet.yaml",
+          version: "1.2.0",
+        },
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts empty dependency file", () => {
+    const result = FacetsYamlSchema.safeParse({})
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts local-only dependencies", () => {
+    const result = FacetsYamlSchema.safeParse({
+      local: ["one", "two"],
+    })
+    expect(result.success).toBe(true)
+  })
+})
+
+describe("FacetsLockSchema", () => {
+  test("accepts valid lockfile", () => {
+    const result = FacetsLockSchema.safeParse({
+      remote: {
+        viper: {
+          url: "https://example.com/facets/viper/facet.yaml",
+          version: "1.2.0",
+          integrity: "sha256-abc123",
+        },
+      },
+    })
+    expect(result.success).toBe(true)
+  })
+
+  test("accepts empty lockfile", () => {
+    const result = FacetsLockSchema.safeParse({})
+    expect(result.success).toBe(true)
+  })
+})
+
+describe("normalizeRequires", () => {
+  test("returns empty array for undefined", () => {
+    expect(normalizeRequires(undefined)).toEqual([])
+  })
+
+  test("wraps string in array", () => {
+    expect(normalizeRequires("gh --version")).toEqual(["gh --version"])
+  })
+
+  test("passes array through", () => {
+    expect(normalizeRequires(["a", "b"])).toEqual(["a", "b"])
+  })
+})
+
+describe("resolvePromptPath", () => {
+  test("returns string prompt as-is", () => {
+    expect(resolvePromptPath("prompts/a.md")).toBe("prompts/a.md")
+  })
+
+  test("returns file path from object", () => {
+    expect(resolvePromptPath({ file: "prompts/a.md" })).toBe("prompts/a.md")
+  })
+
+  test("returns null for url prompt", () => {
+    expect(resolvePromptPath({ url: "https://example.com/prompt" })).toBeNull()
+  })
+})