@agent-facets/core 0.1.1

package/src/build/validate-platforms.ts

@@ -0,0 +1,89 @@
+import { type } from 'arktype'
+import type { FacetManifest } from '../schemas/facet-manifest.ts'
+import type { ValidationError } from '../types.ts'
+
+// --- Known platform schemas ---
+
+/** OpenCode platform config schema */
+const OpenCodePlatformSchema = type({
+  'tools?': type.Record('string', 'boolean'),
+  'model?': 'string',
+})
+
+/** Claude Code platform config schema */
+const ClaudeCodePlatformSchema = type({
+  'tools?': type.Record('string', 'boolean'),
+  'permissions?': type.Record('string', 'boolean'),
+})
+
+/** Map of known platform names to their ArkType validators */
+const KNOWN_PLATFORMS: Record<string, (data: unknown) => unknown> = {
+  opencode: (data) => OpenCodePlatformSchema(data),
+  'claude-code': (data) => ClaudeCodePlatformSchema(data),
+}
+
+export interface PlatformValidationResult {
+  errors: ValidationError[]
+  warnings: string[]
+}
+
+/**
+ * Validates platform configuration for all assets that declare `platforms`.
+ * Known platforms are validated against their schema — invalid config is an error.
+ * Unknown platforms produce a warning but do not cause failure.
+ */
+export function validatePlatformConfigs(manifest: FacetManifest): PlatformValidationResult {
+  const errors: ValidationError[] = []
+  const warnings: string[] = []
+
+  // Check skills
+  if (manifest.skills) {
+    for (const [name, skill] of Object.entries(manifest.skills)) {
+      if (skill.platforms) {
+        validateAssetPlatforms(`skills.${name}`, skill.platforms, errors, warnings)
+      }
+    }
+  }
+
+  // Check agents
+  if (manifest.agents) {
+    for (const [name, agent] of Object.entries(manifest.agents)) {
+      if (agent.platforms) {
+        validateAssetPlatforms(`agents.${name}`, agent.platforms, errors, warnings)
+      }
+    }
+  }
+
+  // Commands don't have platforms in the current schema, but if they ever do,
+  // they'd be validated here uniformly.
+
+  return { errors, warnings }
+}
+
+function validateAssetPlatforms(
+  assetPath: string,
+  platforms: Record<string, unknown>,
+  errors: ValidationError[],
+  warnings: string[],
+): void {
+  for (const [platformName, config] of Object.entries(platforms)) {
+    const validator = KNOWN_PLATFORMS[platformName]
+
+    if (!validator) {
+      warnings.push(`${assetPath}: unknown platform "${platformName}" — config will not be validated`)
+      continue
+    }
+
+    const result = validator(config)
+    if (result instanceof type.errors) {
+      for (const err of result) {
+        errors.push({
+          path: `${assetPath}.platforms.${platformName}.${err.path.join('.')}`,
+          message: `Invalid platform config for "${platformName}" on ${assetPath}: ${err.message}`,
+          expected: err.expected,
+          actual: String(err.actual),
+        })
+      }
+    }
+  }
+}

package/src/build/write-output.ts

@@ -0,0 +1,34 @@
+import { mkdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { BuildManifest } from '../schemas/build-manifest.ts'
+import type { BuildResult } from './pipeline.ts'
+
+const DIST_DIR = 'dist'
+const BUILD_MANIFEST_FILE = 'build-manifest.json'
+
+/**
+ * Writes the build output to dist/.
+ *
+ * - Cleans (removes and recreates) the dist/ directory
+ * - Writes the .facet archive (gzip-compressed tar)
+ * - Writes build-manifest.json with integrity hash and per-asset hashes
+ */
+export async function writeBuildOutput(result: BuildResult, rootDir: string): Promise<void> {
+  const distDir = join(rootDir, DIST_DIR)
+
+  // Clean previous output
+  await rm(distDir, { recursive: true, force: true })
+  await mkdir(distDir, { recursive: true })
+
+  // Write the .facet archive
+  await Bun.write(join(distDir, result.archiveFilename), result.archiveBytes)
+
+  // Write build manifest
+  const manifest: BuildManifest = {
+    facetVersion: 1,
+    archive: result.archiveFilename,
+    integrity: result.integrity,
+    assets: result.assetHashes,
+  }
+  await Bun.write(join(distDir, BUILD_MANIFEST_FILE), JSON.stringify(manifest, null, 2))
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// types
+
+export type { ArchiveEntry } from './build/content-hash.ts'
+export {
+  assembleTar,
+  collectArchiveEntries,
+  compressArchive,
+  computeAssetHashes,
+  computeContentHash,
+} from './build/content-hash.ts'
+export { detectNamingCollisions } from './build/detect-collisions.ts'
+export type { BuildFailure, BuildProgress, BuildResult } from './build/pipeline.ts'
+// build pipeline
+export { runBuildPipeline } from './build/pipeline.ts'
+export { validateCompactFacets } from './build/validate-facets.ts'
+export type { PlatformValidationResult } from './build/validate-platforms.ts'
+export { validatePlatformConfigs } from './build/validate-platforms.ts'
+export { writeBuildOutput } from './build/write-output.ts'
+export type { ResolvedFacetManifest } from './loaders/facet.ts'
+// loaders
+export { FACET_MANIFEST_FILE, loadManifest, resolvePrompts } from './loaders/facet.ts'
+export { loadServerManifest } from './loaders/server.ts'
+export type { BuildManifest } from './schemas/build-manifest.ts'
+export { BuildManifestSchema } from './schemas/build-manifest.ts'
+export type { FacetManifest } from './schemas/facet-manifest.ts'
+// schemas
+export {
+  checkFacetManifestConstraints,
+  FacetManifestSchema,
+} from './schemas/facet-manifest.ts'
+export type { Lockfile } from './schemas/lockfile.ts'
+export { LockfileSchema } from './schemas/lockfile.ts'
+export type { ServerManifest } from './schemas/server-manifest.ts'
+export { ServerManifestSchema } from './schemas/server-manifest.ts'
+export type { Result, ValidationError } from './types.ts'

package/src/loaders/facet.ts

@@ -0,0 +1,180 @@
+import { join } from 'node:path'
+import { type } from 'arktype'
+import { checkFacetManifestConstraints, type FacetManifest, FacetManifestSchema } from '../schemas/facet-manifest.ts'
+import type { Result, ValidationError } from '../types.ts'
+import { mapArkErrors, parseJson, readFile } from './validate.ts'
+
+export const FACET_MANIFEST_FILE = 'facet.json'
+
+/**
+ * Loads and validates a facet manifest from the specified directory.
+ *
+ * Reads the facet manifest, parses JSON, validates against the schema, and checks
+ * business-rule constraints. Returns a discriminated result — either the
+ * validated manifest or structured errors.
+ */
+export async function loadManifest(dir: string): Promise<Result<FacetManifest>> {
+  const filePath = join(dir, FACET_MANIFEST_FILE)
+
+  // Phase 0: Read the file
+  const fileResult = await readFile(filePath)
+  if (!fileResult.ok) {
+    return fileResult
+  }
+
+  // Phase 1: Parse JSON
+  const jsonResult = parseJson(fileResult.content)
+  if (!jsonResult.ok) {
+    return jsonResult
+  }
+
+  // Phase 2: Schema validation
+  const validated = FacetManifestSchema(jsonResult.data)
+  if (validated instanceof type.errors) {
+    return { ok: false, errors: mapArkErrors(validated) }
+  }
+
+  // Phase 3: Business-rule constraints
+  const constraintErrors = checkFacetManifestConstraints(validated)
+  if (constraintErrors.length > 0) {
+    return { ok: false, errors: constraintErrors }
+  }
+
+  return { ok: true, data: validated }
+}
+
+/**
+ * A manifest with all prompts resolved to their string content.
+ * File paths are derived from convention: `<type>/<name>.md`.
+ */
+export interface ResolvedFacetManifest {
+  name: string
+  version: string
+  description?: string
+  author?: string
+  skills?: Record<
+    string,
+    {
+      description: string
+      prompt: string
+      platforms?: Record<string, unknown>
+    }
+  >
+  agents?: Record<
+    string,
+    {
+      description: string
+      prompt: string
+      platforms?: Record<string, unknown>
+    }
+  >
+  commands?: Record<
+    string,
+    {
+      description: string
+      prompt: string
+    }
+  >
+  facets?: FacetManifest['facets']
+  servers?: FacetManifest['servers']
+}
+
+/**
+ * Resolves prompt content for all skills, agents, and commands by reading
+ * files at conventional paths relative to the facet root directory.
+ *
+ * The convention is `<type>/<name>.md` — for example, a skill named
+ * "code-review" resolves to `skills/code-review.md`.
+ *
+ * This also serves as file existence verification for all three asset types —
+ * if an expected file doesn't exist, resolution fails with an error identifying
+ * the asset and the expected file path.
+ *
+ * Returns a new manifest with all prompts resolved to strings, or an error
+ * result identifying which prompt failed and why.
+ */
+export async function resolvePrompts(manifest: FacetManifest, rootDir: string): Promise<Result<ResolvedFacetManifest>> {
+  const errors: ValidationError[] = []
+
+  // Resolve skill prompts from skills/<name>.md
+  let resolvedSkills: ResolvedFacetManifest['skills'] | undefined
+  if (manifest.skills) {
+    resolvedSkills = {}
+    for (const [name, skill] of Object.entries(manifest.skills)) {
+      const resolvedPrompt = await resolveAssetPrompt('skills', name, rootDir)
+      if (typeof resolvedPrompt === 'string') {
+        resolvedSkills[name] = { ...skill, prompt: resolvedPrompt }
+      } else {
+        errors.push(resolvedPrompt)
+      }
+    }
+  }
+
+  // Resolve agent prompts from agents/<name>.md
+  let resolvedAgents: ResolvedFacetManifest['agents'] | undefined
+  if (manifest.agents) {
+    resolvedAgents = {}
+    for (const [name, agent] of Object.entries(manifest.agents)) {
+      const resolvedPrompt = await resolveAssetPrompt('agents', name, rootDir)
+      if (typeof resolvedPrompt === 'string') {
+        resolvedAgents[name] = { ...agent, prompt: resolvedPrompt }
+      } else {
+        errors.push(resolvedPrompt)
+      }
+    }
+  }
+
+  // Resolve command prompts from commands/<name>.md
+  let resolvedCommands: ResolvedFacetManifest['commands'] | undefined
+  if (manifest.commands) {
+    resolvedCommands = {}
+    for (const [name, command] of Object.entries(manifest.commands)) {
+      const resolvedPrompt = await resolveAssetPrompt('commands', name, rootDir)
+      if (typeof resolvedPrompt === 'string') {
+        resolvedCommands[name] = { ...command, prompt: resolvedPrompt }
+      } else {
+        errors.push(resolvedPrompt)
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors }
+  }
+
+  const resolved: ResolvedFacetManifest = {
+    name: manifest.name,
+    version: manifest.version,
+    ...(manifest.description !== undefined && { description: manifest.description }),
+    ...(manifest.author !== undefined && { author: manifest.author }),
+    ...(resolvedSkills !== undefined && { skills: resolvedSkills }),
+    ...(resolvedAgents !== undefined && { agents: resolvedAgents }),
+    ...(resolvedCommands !== undefined && { commands: resolvedCommands }),
+    ...(manifest.facets !== undefined && { facets: manifest.facets }),
+    ...(manifest.servers !== undefined && { servers: manifest.servers }),
+  }
+
+  return { ok: true, data: resolved }
+}
+
+/**
+ * Resolves prompt content for a single asset by reading <type>/<name>.md.
+ * Returns the file content as a string, or a ValidationError if the file doesn't exist.
+ */
+async function resolveAssetPrompt(assetType: string, name: string, rootDir: string): Promise<string | ValidationError> {
+  const relativePath = `${assetType}/${name}.md`
+  const filePath = join(rootDir, relativePath)
+  const file = Bun.file(filePath)
+  const exists = await file.exists()
+
+  if (!exists) {
+    return {
+      path: `${assetType}.${name}`,
+      message: `Prompt file not found: ${relativePath} (resolved to ${filePath})`,
+      expected: 'file to exist',
+      actual: 'file not found',
+    }
+  }
+
+  return file.text()
+}

package/src/loaders/server.ts

@@ -0,0 +1,37 @@
+import { join } from 'node:path'
+import { type } from 'arktype'
+import { type ServerManifest, ServerManifestSchema } from '../schemas/server-manifest.ts'
+import type { Result } from '../types.ts'
+import { mapArkErrors, parseJson, readFile } from './validate.ts'
+
+const SERVER_MANIFEST_FILE = 'server.json'
+
+/**
+ * Loads and validates a server manifest from the specified directory.
+ *
+ * Reads the server manifest, parses JSON, validates against the schema, and returns
+ * a discriminated result — either the validated manifest or structured errors.
+ */
+export async function loadServerManifest(dir: string): Promise<Result<ServerManifest>> {
+  const filePath = join(dir, SERVER_MANIFEST_FILE)
+
+  // Phase 0: Read the file
+  const fileResult = await readFile(filePath)
+  if (!fileResult.ok) {
+    return fileResult
+  }
+
+  // Phase 1: Parse JSON
+  const jsonResult = parseJson(fileResult.content)
+  if (!jsonResult.ok) {
+    return jsonResult
+  }
+
+  // Phase 2: Schema validation
+  const validated = ServerManifestSchema(jsonResult.data)
+  if (validated instanceof type.errors) {
+    return { ok: false, errors: mapArkErrors(validated) }
+  }
+
+  return { ok: true, data: validated }
+}

package/src/loaders/validate.ts

@@ -0,0 +1,64 @@
+import type { type } from 'arktype'
+import type { ValidationError } from '../types.ts'
+
+/**
+ * Maps ArkType errors to our public ValidationError type.
+ * Decouples the public API from ArkType internals.
+ */
+export function mapArkErrors(errors: InstanceType<typeof type.errors>): ValidationError[] {
+  return errors.map((err) => ({
+    path: err.path.join('.'),
+    message: err.message,
+    expected: err.expected ?? 'unknown',
+    actual: err.actual ?? 'unknown',
+  }))
+}
+
+/**
+ * Parses a JSON string. Returns the parsed data or a ValidationError array.
+ */
+export function parseJson(jsonContent: string): { ok: true; data: unknown } | { ok: false; errors: ValidationError[] } {
+  try {
+    const parsed = JSON.parse(jsonContent)
+    return { ok: true, data: parsed }
+  } catch (err) {
+    const message = err instanceof SyntaxError ? err.message : 'Unknown JSON parse error'
+    return {
+      ok: false,
+      errors: [
+        {
+          path: '',
+          message: `JSON syntax error: ${message}`,
+          expected: 'valid JSON',
+          actual: 'malformed JSON',
+        },
+      ],
+    }
+  }
+}
+
+/**
+ * Reads a file from disk. Returns the text content or a ValidationError array.
+ */
+export async function readFile(
+  filePath: string,
+): Promise<{ ok: true; content: string } | { ok: false; errors: ValidationError[] }> {
+  const file = Bun.file(filePath)
+  const exists = await file.exists()
+  if (!exists) {
+    return {
+      ok: false,
+      errors: [
+        {
+          path: '',
+          message: `File not found: ${filePath}`,
+          expected: 'file to exist',
+          actual: 'file not found',
+        },
+      ],
+    }
+  }
+
+  const content = await file.text()
+  return { ok: true, content }
+}

package/src/schemas/build-manifest.ts

@@ -0,0 +1,15 @@
+import { type } from 'arktype'
+
+/**
+ * Schema for the build manifest (build-manifest.json).
+ * Written by `facet build` alongside the .facet archive.
+ */
+export const BuildManifestSchema = type({
+  facetVersion: 'number',
+  archive: 'string',
+  integrity: /^sha256:[a-f0-9]{64}$/,
+  assets: type.Record('string', 'string'),
+})
+
+/** Inferred TypeScript type for a validated build manifest */
+export type BuildManifest = typeof BuildManifestSchema.infer

package/src/schemas/facet-manifest.ts

@@ -0,0 +1,113 @@
+import { type } from 'arktype'
+
+// --- Sub-schemas ---
+
+/** Skill descriptor — description is required, prompt resolved from skills/<name>.md */
+const SkillDescriptor = type({
+  description: 'string',
+  'platforms?': type.Record('string', 'unknown'),
+})
+
+/** Agent descriptor — description is required, prompt resolved from agents/<name>.md */
+const AgentDescriptor = type({
+  description: 'string',
+  'platforms?': type.Record('string', 'unknown'),
+})
+
+/** Command descriptor — description is required, prompt resolved from commands/<name>.md */
+const CommandDescriptor = type({
+  description: 'string',
+})
+
+/** Selective facets entry — cherry-pick specific assets from another facet */
+const SelectiveFacetsEntry = type({
+  name: 'string',
+  version: 'string',
+  'skills?': 'string[]',
+  'agents?': 'string[]',
+  'commands?': 'string[]',
+})
+
+/** Facets entry: compact string ("name@version") or selective object */
+const FacetsEntry = type('string').or(SelectiveFacetsEntry)
+
+/** Server reference: source-mode (floor version string) or ref-mode (OCI image object) */
+const ServerReference = type('string').or({ image: 'string' })
+
+// --- Main schema ---
+
+/**
+ * The structural schema for the facet manifest — validates shape only.
+ * Custom constraints (at least one text asset, selective entry must select at least one type)
+ * are checked post-validation by checkFacetManifestConstraints().
+ */
+export const FacetManifestSchema = type({
+  name: 'string',
+  version: 'string',
+  'description?': 'string',
+  'author?': 'string',
+  'skills?': type.Record('string', SkillDescriptor),
+  'agents?': type.Record('string', AgentDescriptor),
+  'commands?': type.Record('string', CommandDescriptor),
+  'facets?': FacetsEntry.array(),
+  'servers?': type.Record('string', ServerReference),
+})
+
+/** Inferred TypeScript type for a validated facet manifest */
+export type FacetManifest = typeof FacetManifestSchema.infer
+
+// --- Custom validation ---
+
+export interface FacetManifestError {
+  path: string
+  message: string
+  expected: string
+  actual: string
+}
+
+/**
+ * Checks business-rule constraints that ArkType's structural validation cannot express:
+ * 1. At least one text asset must be present (skills, agents, commands, or facets)
+ * 2. Selective facets entries must include at least one asset type
+ */
+export function checkFacetManifestConstraints(manifest: FacetManifest): FacetManifestError[] {
+  const errors: FacetManifestError[] = []
+
+  // Constraint 1: at least one text asset
+  const hasSkills = manifest.skills && Object.keys(manifest.skills).length > 0
+  const hasAgents = manifest.agents && Object.keys(manifest.agents).length > 0
+  const hasCommands = manifest.commands && Object.keys(manifest.commands).length > 0
+  const hasFacets = manifest.facets && manifest.facets.length > 0
+
+  if (!hasSkills && !hasAgents && !hasCommands && !hasFacets) {
+    errors.push({
+      path: '',
+      message: 'Manifest must include at least one text asset (skills, agents, commands, or facets)',
+      expected: 'at least one of: skills, agents, commands, facets',
+      actual: 'none present',
+    })
+  }
+
+  // Constraint 2: selective facets entries must select at least one asset type
+  if (manifest.facets) {
+    for (let i = 0; i < manifest.facets.length; i++) {
+      const entry = manifest.facets[i]
+      if (typeof entry === 'object') {
+        const hasSelectedSkills = entry.skills && entry.skills.length > 0
+        const hasSelectedAgents = entry.agents && entry.agents.length > 0
+        const hasSelectedCommands = entry.commands && entry.commands.length > 0
+
+        if (!hasSelectedSkills && !hasSelectedAgents && !hasSelectedCommands) {
+          errors.push({
+            path: `facets[${i}]`,
+            message: 'Selective facets entry must include at least one asset type (skills, agents, or commands)',
+            expected: 'at least one of: skills, agents, commands',
+            actual: 'none selected',
+          })
+        }
+      }
+    }
+  }
+
+  return errors
+}

package/src/schemas/lockfile.ts

@@ -0,0 +1,37 @@
+import { type } from 'arktype'
+
+/** Facet identity section of the lockfile */
+const LockfileFacet = type({
+  name: 'string',
+  version: 'string',
+  integrity: 'string',
+})
+
+/** Source-mode server entry — resolved from the facets registry */
+const SourceModeServerEntry = type({
+  version: 'string',
+  integrity: 'string',
+  api_surface: 'string',
+})
+
+/** Ref-mode server entry — resolved from an OCI registry */
+const RefModeServerEntry = type({
+  image: 'string',
+  digest: 'string',
+  api_surface: 'string',
+})
+
+/** A lockfile server entry is either source-mode or ref-mode */
+const ServerEntry = SourceModeServerEntry.or(RefModeServerEntry)
+
+/**
+ * Schema for facets.lock — the lockfile recording resolved installation state.
+ * Matches the shape defined in ADR-003.
+ */
+export const LockfileSchema = type({
+  facet: LockfileFacet,
+  'servers?': type.Record('string', ServerEntry),
+})
+
+/** Inferred TypeScript type for a validated lockfile */
+export type Lockfile = typeof LockfileSchema.infer

package/src/schemas/server-manifest.ts

@@ -0,0 +1,17 @@
+import { type } from 'arktype'
+
+/**
+ * Schema for the server manifest (server.json).
+ * Matches the shape defined in ADR-005.
+ */
+export const ServerManifestSchema = type({
+  name: 'string',
+  version: 'string',
+  runtime: 'string',
+  entry: 'string',
+  'description?': 'string',
+  'author?': 'string',
+})
+
+/** Inferred TypeScript type for a validated server manifest */
+export type ServerManifest = typeof ServerManifestSchema.infer

package/src/types.ts

@@ -0,0 +1,20 @@
+/**
+ * A structured validation error decoupled from ArkType internals.
+ * Used by all loaders to report schema and parsing failures.
+ */
+export interface ValidationError {
+  /** Dot-separated path to the invalid field (e.g., "agents.reviewer.prompt") */
+  path: string
+  /** Human-readable error message */
+  message: string
+  /** What was expected at this location */
+  expected: string
+  /** What was actually found */
+  actual: string
+}
+
+/**
+ * Discriminated result type returned by all loaders.
+ * Callers check `ok` to determine success or failure.
+ */
+export type Result<T> = { ok: true; data: T } | { ok: false; errors: ValidationError[] }

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src"]
+}