@ex-machina/facets 0.1.0

package/src/registry/files.ts

@@ -0,0 +1,60 @@
+import yaml from "js-yaml"
+import { FacetsYamlSchema, FacetsLockSchema, type FacetsYaml, type FacetsLock } from "./schemas.ts"
+
+/**
+ * Platform-specific paths for facets config files.
+ * In v1, this is always .opencode/.
+ */
+export function facetsYamlPath(projectRoot: string): string {
+  return `${projectRoot}/.opencode/facets.yaml`
+}
+
+export function facetsLockPath(projectRoot: string): string {
+  return `${projectRoot}/.opencode/facets.lock`
+}
+
+export function localFacetsDir(projectRoot: string): string {
+  return `${projectRoot}/.opencode/facets`
+}
+
+// --- facets.yaml ---
+
+export async function readFacetsYaml(projectRoot: string): Promise<FacetsYaml> {
+  const filePath = facetsYamlPath(projectRoot)
+  try {
+    const raw = await Bun.file(filePath).text()
+    const parsed = yaml.load(raw)
+    const result = FacetsYamlSchema.safeParse(parsed)
+    if (result.success) return result.data
+    return { remote: {}, local: [] }
+  } catch {
+    return { remote: {}, local: [] }
+  }
+}
+
+export async function writeFacetsYaml(projectRoot: string, data: FacetsYaml): Promise<void> {
+  const filePath = facetsYamlPath(projectRoot)
+  const content = yaml.dump(data, { lineWidth: -1, noRefs: true })
+  await Bun.write(filePath, content)
+}
+
+// --- facets.lock ---
+
+export async function readFacetsLock(projectRoot: string): Promise<FacetsLock> {
+  const filePath = facetsLockPath(projectRoot)
+  try {
+    const raw = await Bun.file(filePath).text()
+    const parsed = yaml.load(raw)
+    const result = FacetsLockSchema.safeParse(parsed)
+    if (result.success) return result.data
+    return { remote: {} }
+  } catch {
+    return { remote: {} }
+  }
+}
+
+export async function writeFacetsLock(projectRoot: string, data: FacetsLock): Promise<void> {
+  const filePath = facetsLockPath(projectRoot)
+  const content = yaml.dump(data, { lineWidth: -1, noRefs: true })
+  await Bun.write(filePath, content)
+}

package/src/registry/loader.ts

@@ -0,0 +1,42 @@
+import yaml from "js-yaml"
+import { FacetManifestSchema, type FacetManifest } from "./schemas.ts"
+
+export interface LoadManifestSuccess {
+  success: true
+  manifest: FacetManifest
+}
+
+export interface LoadManifestError {
+  success: false
+  error: string
+}
+
+export type LoadManifestResult = LoadManifestSuccess | LoadManifestError
+
+/**
+ * Load and validate a facet.yaml manifest from the given path.
+ * Returns the parsed manifest or a structured error.
+ */
+export async function loadManifest(manifestPath: string): Promise<LoadManifestResult> {
+  let raw: string
+  try {
+    raw = await Bun.file(manifestPath).text()
+  } catch {
+    return { success: false, error: `Cannot read manifest: ${manifestPath}` }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = yaml.load(raw)
+  } catch (err) {
+    return { success: false, error: `Invalid YAML in manifest: ${err}` }
+  }
+
+  const result = FacetManifestSchema.safeParse(parsed)
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+    return { success: false, error: `Invalid manifest: ${issues}` }
+  }
+
+  return { success: true, manifest: result.data }
+}

package/src/registry/schemas.ts

@@ -0,0 +1,119 @@
+import { z } from "zod/v4"
+
+// --- Prompt field: string (file path) or object with file/url ---
+
+const PromptSchema = z.union([
+  z.string(),
+  z.object({ file: z.string() }),
+  z.object({ url: z.string().url() }),
+])
+
+// --- Agent descriptor ---
+
+const AgentPlatformOpencode = z
+  .object({
+    tools: z.union([
+      z.record(z.string(), z.boolean()),
+      z.array(z.string()),
+    ]).optional(),
+  })
+  .passthrough()
+
+const AgentPlatformGeneric = z.record(z.string(), z.unknown())
+
+const AgentDescriptorSchema = z.object({
+  description: z.string().optional(),
+  prompt: PromptSchema,
+  platforms: z
+    .object({
+      opencode: AgentPlatformOpencode.optional(),
+    })
+    .catchall(AgentPlatformGeneric)
+    .optional(),
+})
+
+// --- Command descriptor ---
+
+const CommandDescriptorSchema = z.object({
+  description: z.string().optional(),
+  prompt: PromptSchema,
+})
+
+// --- Platform section ---
+
+const PlatformOpencodeSchema = z.object({
+  tools: z.array(z.string()).optional(),
+})
+
+const PlatformsSchema = z
+  .object({
+    opencode: PlatformOpencodeSchema.optional(),
+  })
+  .catchall(z.record(z.string(), z.unknown()))
+
+// --- Requires: string or array of strings ---
+
+const RequiresSchema = z.union([z.string(), z.array(z.string())])
+
+// --- FacetManifest (facet.yaml) ---
+
+export const FacetManifestSchema = z
+  .object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    description: z.string().optional(),
+    author: z.string().optional(),
+    requires: RequiresSchema.optional(),
+    skills: z.array(z.string()).optional(),
+    agents: z.record(z.string(), AgentDescriptorSchema).optional(),
+    commands: z.record(z.string(), CommandDescriptorSchema).optional(),
+    platforms: PlatformsSchema.optional(),
+  })
+  .passthrough()
+
+export type FacetManifest = z.infer<typeof FacetManifestSchema>
+
+// --- FacetsYaml (facets.yaml — project dependency file) ---
+
+const RemoteEntrySchema = z.object({
+  url: z.string().url(),
+  version: z.string().optional(),
+})
+
+export const FacetsYamlSchema = z.object({
+  remote: z.record(z.string(), RemoteEntrySchema).optional(),
+  local: z.array(z.string()).optional(),
+})
+
+export type FacetsYaml = z.infer<typeof FacetsYamlSchema>
+
+// --- FacetsLock (facets.lock — lockfile) ---
+
+const LockEntrySchema = z.object({
+  url: z.string().url(),
+  version: z.string(),
+  integrity: z.string(),
+})
+
+export const FacetsLockSchema = z.object({
+  remote: z.record(z.string(), LockEntrySchema).optional(),
+})
+
+export type FacetsLock = z.infer<typeof FacetsLockSchema>
+
+// --- Helpers ---
+
+/** Normalize requires to always be an array */
+export function normalizeRequires(requires: string | string[] | undefined): string[] {
+  if (!requires) return []
+  if (typeof requires === "string") return [requires]
+  return requires
+}
+
+/** Resolve a prompt field to a file path relative to the facet directory */
+export function resolvePromptPath(prompt: z.infer<typeof PromptSchema>): string | null {
+  if (typeof prompt === "string") return prompt
+  if ("file" in prompt) return prompt.file
+  // URL prompts are not resolved to local paths
+  return null
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}