@ex-machina/facets 0.1.0 → 0.2.2

package/.turbo/turbo-test.log

@@ -0,0 +1,87 @@
+$ bun test
+bun test v1.3.10 (30e609e0)
+
+::group::src/__tests__/e2e.test.ts:
+Registered facets MCP server in .opencode/opencode.jsonc
+Created facets.yaml
+(pass) End-to-end > init → list → install → verify resources → uninstall [34.00ms]
+Registered facets MCP server in .opencode/opencode.jsonc
+Created facets.yaml
+Project already configured for facets.
+(pass) End-to-end > init is idempotent [3.00ms]
+
+::endgroup::
+
+::group::src/installation/__tests__/install.test.ts:
+(pass) installFacet > installs local facet with skill [5.00ms]
+(pass) installFacet > installs agent with assembled frontmatter [2.00ms]
+(pass) installFacet > installs command with assembled frontmatter [2.00ms]
+(pass) installFacet > installs platform tools [4.00ms]
+(pass) installFacet > returns not_found for unknown facet [10.00ms]
+(pass) installFacet > runs prereq checks and fails on bad command [3.00ms]
+(pass) installFacet > forcePrereqCheck re-runs checks even when previously confirmed [7.00ms]
+(pass) installFacet > installs facet from cache when not found locally [15.00ms]
+(pass) installFacet > user declining prereqs cancels install [2.00ms]
+(pass) uninstallFacet > removes installed resources [5.00ms]
+(pass) uninstallFacet > returns not_found for unknown facet [1.00ms]
+
+::endgroup::
+
+::group::src/registry/__tests__/schemas.test.ts:
+(pass) FacetManifest > accepts valid minimal manifest
+(pass) FacetManifest > accepts full manifest with all fields
+(pass) FacetManifest > rejects manifest without name [1.00ms]
+(pass) FacetManifest > rejects manifest without version
+(pass) FacetManifest > tolerates unrecognized fields
+(pass) FacetManifest > accepts requires as string
+(pass) FacetManifest > accepts requires as array [1.00ms]
+(pass) FacetManifest > accepts prompt as string
+(pass) FacetManifest > accepts prompt as object with file
+(pass) FacetManifest > accepts prompt as object with url
+(pass) FacetManifest > accepts agent with array-style tools
+(pass) FacetsYaml > accepts valid dependency file
+(pass) FacetsYaml > accepts empty dependency file
+(pass) FacetsYaml > accepts local-only dependencies
+(pass) FacetsLock > accepts valid lockfile
+(pass) FacetsLock > accepts empty lockfile [1.00ms]
+(pass) normalizeRequires > returns empty array for undefined
+(pass) normalizeRequires > wraps string in array
+(pass) normalizeRequires > passes array through
+(pass) resolvePromptPath > returns string prompt as-is
+(pass) resolvePromptPath > returns file path from object
+(pass) resolvePromptPath > returns null for url prompt
+
+::endgroup::
+
+::group::src/registry/__tests__/loader.test.ts:
+(pass) loadManifest > loads valid manifest [1.00ms]
+(pass) loadManifest > returns error for missing file [1.00ms]
+(pass) loadManifest > returns error for invalid YAML [1.00ms]
+(pass) loadManifest > returns error for missing required fields [1.00ms]
+(pass) loadManifest > tolerates unrecognized fields
+
+::endgroup::
+
+::group::src/discovery/__tests__/cache.test.ts:
+(pass) resolveUrl > resolves relative path against manifest URL [2.00ms]
+(pass) resolveUrl > resolves path in subdirectory
+(pass) resolveUrl > resolves against nested base path [1.00ms]
+(pass) cacheFacet > lockfile updated when remote facet is cached [2.00ms]
+(pass) cacheFacet > fetches and caches resource files declared in manifest [3.00ms]
+
+::endgroup::
+
+::group::src/discovery/__tests__/list.test.ts:
+(pass) listFacets > returns empty list when no facets exist [1.00ms]
+(pass) listFacets > includes local facets [2.00ms]
+(pass) listFacets > reports installed status correctly [2.00ms]
+(pass) listFacets > includes requires as metadata [1.00ms]
+(pass) listFacets > lists resource summaries [2.00ms]
+(pass) listFacets > includes remote facets from facets.yaml [2.00ms]
+
+::endgroup::
+
+ 51 pass
+ 0 fail
+ 112 expect() calls
+Ran 51 tests across 6 files. [481.00ms]

package/.turbo/turbo-types.log

@@ -0,0 +1 @@
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @ex-machina/facets
+
+## 0.2.2
+
+### Patch Changes
+
+- 124d984: Provenance changes
+
+## 0.2.1
+
+### Patch Changes
+
+- b052d3d: Automatically make PRs that can merge
+
+## 0.2.0
+
+### Minor Changes
+
+- e46bfb5: Test changeset workflow

package/README.md

@@ -0,0 +1,38 @@
+# @ex-machina/facets
+
+[![npm](https://img.shields.io/npm/v/@ex-machina/facets)](https://www.npmjs.com/package/@ex-machina/facets)
+
+Core library and CLI for discovering, installing, and managing facets — modular skills, agents, commands, and tools that extend AI coding assistants.
+
+> **Status**: Early development (v0.1.0). APIs may change.
+
+## CLI
+
+```sh
+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
+```
+
+## Library
+
+The package also exports its core functions for programmatic use:
+
+- **Registry** — `loadManifest`, `FacetManifestSchema`, `FacetsYamlSchema`, `FacetsLockSchema`
+- **Discovery** — `listFacets`, `cacheFacet`, `updateFacet`, `updateAllFacets`, `clearCache`
+- **Installation** — `installFacet`, `uninstallFacet`
+
+## License
+
+[MIT](../../LICENSE)

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@ex-machina/facets",
-  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ex-machina-co/facets",
+    "directory": "packages/facets"
+  },
+  "version": "0.2.2",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
@@ -13,9 +18,9 @@
     "test": "bun test"
   },
   "dependencies": {
+    "arktype": "2.1.29",
     "comment-json": "^4.2.5",
-    "js-yaml": "^4.1.0",
-    "zod": "^4.1.0"
+    "js-yaml": "^4.1.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
@@ -23,5 +28,9 @@
   },
   "peerDependencies": {
     "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   }
 }

package/src/__tests__/e2e.test.ts

@@ -1,28 +1,24 @@
-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"
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import yaml from 'js-yaml'
+import { initProject } from '../cli/init.ts'
+import { listFacets } from '../discovery/list.ts'
+import { installFacet } from '../installation/install.ts'
+import { uninstallFacet } from '../installation/uninstall.ts'
 
 let projectRoot: string
 
 beforeEach(async () => {
-  projectRoot = await mkdtemp(path.join(tmpdir(), "facets-e2e-"))
+  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>,
-) {
+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))
@@ -33,57 +29,57 @@ async function writeLocalFacet(
   }
 }
 
-describe("End-to-end", () => {
-  test("init → list → install → verify resources → uninstall", async () => {
+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")
+    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",
+      'test-facet',
       {
-        name: "test-facet",
-        version: "1.0.0",
-        description: "End-to-end test facet",
-        skills: ["e2e-skill"],
+        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",
+          '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",
+          '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.",
+        '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)
+    expect(list.facets[0]?.name).toBe('test-facet')
+    expect(list.facets[0]?.installed).toBe(false)
 
     // 4. Install
-    const installResult = await installFacet("test-facet", projectRoot)
+    const installResult = await installFacet('test-facet', projectRoot)
     expect(installResult.success).toBe(true)
     if (installResult.success) {
       expect(installResult.resources).toHaveLength(3)
@@ -96,15 +92,15 @@ describe("End-to-end", () => {
 
     // 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.")
+    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)
+    expect(list.facets[0]?.installed).toBe(true)
 
     // 7. Uninstall
-    const uninstallResult = await uninstallFacet("test-facet", projectRoot)
+    const uninstallResult = await uninstallFacet('test-facet', projectRoot)
     expect(uninstallResult.success).toBe(true)
 
     // 8. Verify resources removed
@@ -114,10 +110,10 @@ describe("End-to-end", () => {
 
     // 9. List — should be back to not installed
     list = await listFacets(projectRoot)
-    expect(list.facets[0]!.installed).toBe(false)
+    expect(list.facets[0]?.installed).toBe(false)
   })
 
-  test("init is idempotent", async () => {
+  test('init is idempotent', async () => {
     await initProject(projectRoot)
     await initProject(projectRoot)
 

package/src/cli/init.ts

@@ -1,11 +1,11 @@
-import { parse, stringify } from "comment-json"
-import { facetsYamlPath } from "../registry/files.ts"
+import { parse, stringify } from 'comment-json'
+import { facetsYamlPath } from '../registry/files.ts'
 
-const OPENCODE_CONFIG_PATH = ".opencode/opencode.jsonc"
+const OPENCODE_CONFIG_PATH = '.opencode/opencode.jsonc'
 
 const MCP_SERVER_CONFIG = {
-  type: "local",
-  command: ["bunx", "facets-mcp"],
+  type: 'local',
+  command: ['bunx', 'facets-mcp'],
   enabled: true,
 } as const
 
@@ -30,13 +30,13 @@ export async function initProject(projectRoot: string): Promise<void> {
   } catch {
     // Config doesn't exist — create a new one
     config = {}
-    configText = "{}"
+    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.")
+    console.log('Project already configured for facets.')
     return
   }
 
@@ -46,13 +46,13 @@ export async function initProject(projectRoot: string): Promise<void> {
 
   // Write back preserving comments
   const newConfig = stringify(config, null, 2)
-  await Bun.write(configPath, newConfig + "\n")
+  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")
+    await Bun.write(yamlPath, '# Facet dependencies for this project\nlocal: []\nremote: {}\n')
+    console.log('Created facets.yaml')
   }
 }

package/src/cli.ts

@@ -1,10 +1,26 @@
 #!/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"
+import { createInterface } from 'node:readline'
+import pkg from '../package.json' with { type: 'json' }
+import { cacheFacet } from './discovery/cache.ts'
+import { clearCache } from './discovery/clear.ts'
+import { listFacets } from './discovery/list.ts'
+import { installFacet } from './installation/install.ts'
+import { uninstallFacet } from './installation/uninstall.ts'
+
+async function promptPrereqApproval(commands: string[]): Promise<boolean> {
+  console.log('The following prerequisite checks will be run:')
+  for (const cmd of commands) {
+    console.log(`  ${cmd}`)
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await new Promise<string>((resolve) => {
+    rl.question('Run these prerequisite checks? (y/N) ', resolve)
+  })
+  rl.close()
+
+  return answer.trim().toLowerCase() === 'y' || answer.trim().toLowerCase() === 'yes'
+}
 
 const HELP = `Usage: facets <command> [options]
 
@@ -24,39 +40,39 @@ Options:
 async function main() {
   const args = process.argv.slice(2)
 
-  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  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")
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(pkg.version)
     process.exit(0)
   }
 
   const command = args[0]
 
   switch (command) {
-    case "init":
+    case 'init':
       await cmdInit()
       break
-    case "list":
+    case 'list':
       await cmdList()
       break
-    case "add":
+    case 'add':
       await cmdAdd(args[1])
       break
-    case "install":
+    case 'install':
       await cmdInstall(args[1])
       break
-    case "remove":
+    case 'remove':
       await cmdRemove(args[1])
       break
-    case "update":
+    case 'update':
       await cmdUpdate(args[1])
       break
-    case "cache":
-      if (args[1] === "clear") {
+    case 'cache':
+      if (args[1] === 'clear') {
         await cmdCacheClear()
       } else {
         console.error(`Unknown cache subcommand: ${args[1]}`)
@@ -72,7 +88,7 @@ async function main() {
 }
 
 async function cmdInit() {
-  const { initProject } = await import("./cli/init.ts")
+  const { initProject } = await import('./cli/init.ts')
   await initProject(process.cwd())
 }
 
@@ -81,24 +97,27 @@ async function cmdList() {
   const result = await listFacets(projectRoot)
 
   if (result.facets.length === 0) {
-    console.log("No facets declared.")
+    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"
+    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}`)
     }
+    if (facet.requires.length > 0) {
+      console.log(`    requires: ${facet.requires.join(', ')}`)
+    }
   }
 }
 
 async function cmdAdd(url: string | undefined) {
   if (!url) {
-    console.error("Usage: facets add <url>")
+    console.error('Usage: facets add <url>')
     process.exit(1)
   }
 
@@ -121,7 +140,9 @@ async function cmdInstall(name: string | undefined) {
     const list = await listFacets(projectRoot)
     for (const facet of list.facets) {
       if (!facet.installed) {
-        const result = await installFacet(facet.name, projectRoot)
+        const result = await installFacet(facet.name, projectRoot, {
+          onPrereqApproval: promptPrereqApproval,
+        })
         if (result.success) {
           console.log(`Installed: ${facet.name}`)
         } else {
@@ -132,7 +153,9 @@ async function cmdInstall(name: string | undefined) {
     return
   }
 
-  const result = await installFacet(name, projectRoot)
+  const result = await installFacet(name, projectRoot, {
+    onPrereqApproval: promptPrereqApproval,
+  })
   if (result.success) {
     console.log(`Installed: ${name}`)
     for (const r of result.resources) {
@@ -140,7 +163,7 @@ async function cmdInstall(name: string | undefined) {
     }
   } else {
     console.error(`Failed to install ${name}: ${result.reason}`)
-    if (result.reason === "prereq" && "failure" in result) {
+    if (result.reason === 'prereq' && 'failure' in result) {
       console.error(`  Command failed: ${result.failure.command}`)
     }
     process.exit(1)
@@ -149,7 +172,7 @@ async function cmdInstall(name: string | undefined) {
 
 async function cmdRemove(name: string | undefined) {
   if (!name) {
-    console.error("Usage: facets remove <name>")
+    console.error('Usage: facets remove <name>')
     process.exit(1)
   }
 
@@ -165,7 +188,7 @@ async function cmdRemove(name: string | undefined) {
 }
 
 async function cmdUpdate(name: string | undefined) {
-  const { updateFacet, updateAllFacets } = await import("./discovery/cache.ts")
+  const { updateFacet, updateAllFacets } = await import('./discovery/cache.ts')
 
   if (name) {
     const result = await updateFacet(name, process.cwd())
@@ -197,7 +220,7 @@ async function cmdUpdate(name: string | undefined) {
 
 async function cmdCacheClear() {
   await clearCache()
-  console.log("Cache cleared.")
+  console.log('Cache cleared.')
 }
 
 main().catch((err) => {