@agent-facets/core 0.1.1

package/src/__tests__/lockfile.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from 'bun:test'
+import { type } from 'arktype'
+import { type Lockfile, LockfileSchema } from '../schemas/lockfile.ts'
+
+// --- Valid lockfiles ---
+
+describe('LockfileSchema — valid lockfiles', () => {
+  test('lockfile with source-mode servers', () => {
+    const input = {
+      facet: {
+        name: 'acme-dev',
+        version: '1.0.0',
+        integrity: 'sha256:abc123',
+      },
+      servers: {
+        jira: {
+          version: '1.5.2',
+          integrity: 'sha256:def456',
+          api_surface: 'sha256:789abc',
+        },
+      },
+    }
+    const result = LockfileSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as Lockfile
+    expect(data.facet.name).toBe('acme-dev')
+    expect(data.servers?.jira).toEqual({
+      version: '1.5.2',
+      integrity: 'sha256:def456',
+      api_surface: 'sha256:789abc',
+    })
+  })
+
+  test('lockfile with ref-mode servers', () => {
+    const input = {
+      facet: {
+        name: 'acme-dev',
+        version: '1.0.0',
+        integrity: 'sha256:abc123',
+      },
+      servers: {
+        slack: {
+          image: 'ghcr.io/acme/slack-bot:v2',
+          digest: 'sha256:e4d909',
+          api_surface: 'sha256:567ghi',
+        },
+      },
+    }
+    const result = LockfileSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as Lockfile
+    expect(data.servers?.slack).toEqual({
+      image: 'ghcr.io/acme/slack-bot:v2',
+      digest: 'sha256:e4d909',
+      api_surface: 'sha256:567ghi',
+    })
+  })
+
+  test('lockfile with mixed server types', () => {
+    const input = {
+      facet: {
+        name: 'acme-dev',
+        version: '1.0.0',
+        integrity: 'sha256:abc123',
+      },
+      servers: {
+        jira: {
+          version: '1.5.2',
+          integrity: 'sha256:def456',
+          api_surface: 'sha256:789abc',
+        },
+        slack: {
+          image: 'ghcr.io/acme/slack-bot:v2',
+          digest: 'sha256:e4d909',
+          api_surface: 'sha256:567ghi',
+        },
+      },
+    }
+    const result = LockfileSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+  })
+
+  test('lockfile without servers is valid', () => {
+    const input = {
+      facet: {
+        name: 'no-servers',
+        version: '1.0.0',
+        integrity: 'sha256:abc123',
+      },
+    }
+    const result = LockfileSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as Lockfile
+    expect(data.servers).toBeUndefined()
+  })
+})
+
+// --- Invalid lockfiles ---
+
+describe('LockfileSchema — invalid lockfiles', () => {
+  test('missing facet integrity', () => {
+    const input = {
+      facet: {
+        name: 'acme-dev',
+        version: '1.0.0',
+      },
+    }
+    const result = LockfileSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+  })
+
+  test('incomplete source-mode server entry', () => {
+    const input = {
+      facet: {
+        name: 'acme-dev',
+        version: '1.0.0',
+        integrity: 'sha256:abc123',
+      },
+      servers: {
+        jira: {
+          version: '1.5.2',
+          // missing integrity and api_surface
+        },
+      },
+    }
+    const result = LockfileSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+  })
+
+  test('ref-mode missing digest', () => {
+    const input = {
+      facet: {
+        name: 'acme-dev',
+        version: '1.0.0',
+        integrity: 'sha256:abc123',
+      },
+      servers: {
+        slack: {
+          image: 'ghcr.io/acme/slack-bot:v2',
+          // missing digest and api_surface
+        },
+      },
+    }
+    const result = LockfileSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+  })
+})
+
+// --- Unknown field pass-through ---
+
+describe('LockfileSchema — unknown field tolerance', () => {
+  test('unknown field in lockfile is preserved', () => {
+    const input = {
+      facet: {
+        name: 'acme-dev',
+        version: '1.0.0',
+        integrity: 'sha256:abc123',
+      },
+      generatedAt: '2026-03-08',
+    }
+    const result = LockfileSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as Lockfile & { generatedAt: string }
+    expect(data.generatedAt).toBe('2026-03-08')
+  })
+})

package/src/__tests__/server-loader.test.ts

@@ -0,0 +1,99 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { loadServerManifest } from '../loaders/server.ts'
+
+let testDir: string
+
+beforeAll(async () => {
+  testDir = await mkdtemp(join(tmpdir(), 'server-loader-test-'))
+})
+
+afterAll(async () => {
+  await rm(testDir, { recursive: true, force: true })
+})
+
+async function writeFixture(dir: string, filename: string, content: string) {
+  const path = join(dir, filename)
+  await Bun.write(path, content)
+  return path
+}
+
+async function createFixtureDir(name: string): Promise<string> {
+  const dir = join(testDir, name)
+  await Bun.write(join(dir, '.keep'), '')
+  return dir
+}
+
+describe('loadServerManifest', () => {
+  test('successful load', async () => {
+    const dir = await createFixtureDir('valid-server')
+    await writeFixture(
+      dir,
+      'server.json',
+      JSON.stringify({
+        name: 'jira',
+        version: '1.5.0',
+        runtime: 'bun',
+        entry: 'index.ts',
+        description: 'Jira integration',
+        author: 'acme-org',
+      }),
+    )
+
+    const result = await loadServerManifest(dir)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.name).toBe('jira')
+      expect(result.data.version).toBe('1.5.0')
+      expect(result.data.runtime).toBe('bun')
+      expect(result.data.entry).toBe('index.ts')
+      expect(result.data.description).toBe('Jira integration')
+      expect(result.data.author).toBe('acme-org')
+    }
+  })
+
+  test('file not found', async () => {
+    const dir = await createFixtureDir('missing-server')
+
+    const result = await loadServerManifest(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors).toHaveLength(1)
+      expect(result.errors.at(0)?.message).toContain('File not found')
+    }
+  })
+
+  test('malformed JSON', async () => {
+    const dir = await createFixtureDir('malformed-server')
+    await writeFixture(dir, 'server.json', '{ "name": [unterminated')
+
+    const result = await loadServerManifest(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors.at(0)?.message).toContain('JSON syntax error')
+    }
+  })
+
+  test('validation errors for missing required fields', async () => {
+    const dir = await createFixtureDir('invalid-server')
+    await writeFixture(
+      dir,
+      'server.json',
+      JSON.stringify({
+        name: 'jira',
+        version: '1.5.0',
+      }),
+    )
+
+    const result = await loadServerManifest(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      // Should have errors for missing runtime and entry
+      expect(result.errors.length).toBeGreaterThanOrEqual(1)
+      const messages = result.errors.map((e) => e.message).join(' ')
+      expect(messages).toContain('runtime')
+    }
+  })
+})

package/src/__tests__/server-manifest.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test'
+import { type } from 'arktype'
+import { type ServerManifest, ServerManifestSchema } from '../schemas/server-manifest.ts'
+
+// --- Valid manifests ---
+
+describe('ServerManifestSchema — valid manifests', () => {
+  test('minimal valid server manifest', () => {
+    const input = {
+      name: 'jira',
+      version: '1.5.0',
+      runtime: 'bun',
+      entry: 'index.ts',
+    }
+    const result = ServerManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as ServerManifest
+    expect(data.name).toBe('jira')
+    expect(data.version).toBe('1.5.0')
+    expect(data.runtime).toBe('bun')
+    expect(data.entry).toBe('index.ts')
+  })
+
+  test('server manifest with optional fields', () => {
+    const input = {
+      name: 'jira',
+      version: '1.5.0',
+      description: 'Jira integration',
+      author: 'acme-org',
+      runtime: 'bun',
+      entry: 'index.ts',
+    }
+    const result = ServerManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as ServerManifest
+    expect(data.description).toBe('Jira integration')
+    expect(data.author).toBe('acme-org')
+  })
+})
+
+// --- Invalid manifests ---
+
+describe('ServerManifestSchema — invalid manifests', () => {
+  test('missing runtime', () => {
+    const input = {
+      name: 'jira',
+      version: '1.5.0',
+      entry: 'index.ts',
+    }
+    const result = ServerManifestSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+  })
+
+  test('missing entry', () => {
+    const input = {
+      name: 'jira',
+      version: '1.5.0',
+      runtime: 'bun',
+    }
+    const result = ServerManifestSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+  })
+
+  test('wrong field type', () => {
+    const input = {
+      name: 'jira',
+      version: '1.5.0',
+      runtime: 42,
+      entry: 'index.ts',
+    }
+    const result = ServerManifestSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+  })
+})
+
+// --- Unknown field pass-through ---
+
+describe('ServerManifestSchema — unknown field tolerance', () => {
+  test('unknown field is preserved', () => {
+    const input = {
+      name: 'jira',
+      version: '1.5.0',
+      runtime: 'bun',
+      entry: 'index.ts',
+      license: 'MIT',
+    }
+    const result = ServerManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as ServerManifest & { license: string }
+    expect(data.license).toBe('MIT')
+  })
+})

package/src/build/content-hash.ts

@@ -0,0 +1,102 @@
+import { createTar, type TarFileInput } from 'nanotar'
+import { FACET_MANIFEST_FILE, type ResolvedFacetManifest } from '../loaders/facet.ts'
+
+export interface ArchiveEntry {
+  path: string
+  content: string
+}
+
+/**
+ * Computes a SHA-256 content hash of the given content.
+ * Returns the hash in ADR-004 format: `sha256:<hex>`.
+ */
+export function computeContentHash(content: string | Uint8Array): string {
+  const hex = Bun.CryptoHasher.hash('sha256', content, 'hex')
+  return `sha256:${hex}`
+}
+
+/**
+ * Collects all files that belong in the archive from a resolved manifest.
+ * Returns entries sorted lexicographically by path.
+ *
+ * The manifest content is read separately because the resolved manifest
+ * is a parsed object — we need the original file content for the archive.
+ */
+export function collectArchiveEntries(resolved: ResolvedFacetManifest, manifestContent: string): ArchiveEntry[] {
+  const entries: ArchiveEntry[] = [{ path: FACET_MANIFEST_FILE, content: manifestContent }]
+
+  if (resolved.skills) {
+    for (const [name, skill] of Object.entries(resolved.skills)) {
+      entries.push({ path: `skills/${name}.md`, content: skill.prompt })
+    }
+  }
+
+  if (resolved.agents) {
+    for (const [name, agent] of Object.entries(resolved.agents)) {
+      entries.push({ path: `agents/${name}.md`, content: agent.prompt })
+    }
+  }
+
+  if (resolved.commands) {
+    for (const [name, command] of Object.entries(resolved.commands)) {
+      entries.push({ path: `commands/${name}.md`, content: command.prompt })
+    }
+  }
+
+  entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+
+  return entries
+}
+
+/**
+ * Computes SHA-256 content hashes for each archive entry.
+ * Returns a map of relative path to `sha256:<hex>`.
+ */
+export function computeAssetHashes(entries: ArchiveEntry[]): Record<string, string> {
+  const hashes: Record<string, string> = {}
+  for (const entry of entries) {
+    hashes[entry.path] = computeContentHash(entry.content)
+  }
+  return hashes
+}
+
+/**
+ * Assembles a deterministic uncompressed tar archive from archive entries.
+ *
+ * Determinism is ensured by:
+ * - Entries must be pre-sorted by path (caller responsibility via collectArchiveEntries)
+ * - All metadata is zeroed: mtime=0, uid=0, gid=0, fixed mode, empty user/group
+ *
+ * The tar bytes are what gets content-hashed (the integrity value).
+ * Compression is a separate delivery concern — see {@link compressArchive}.
+ */
+export function assembleTar(entries: ArchiveEntry[]): Uint8Array {
+  const files: TarFileInput[] = entries.map((entry) => ({
+    name: entry.path,
+    data: entry.content,
+  }))
+
+  return createTar(files, {
+    attrs: {
+      mtime: 0,
+      uid: 0,
+      gid: 0,
+      mode: '644',
+      user: '',
+      group: '',
+    },
+  })
+}
+
+/**
+ * Compresses tar bytes with gzip for the `.facet` delivery format.
+ *
+ * Compression is a delivery concern — the integrity hash covers the
+ * uncompressed tar bytes, not the compressed output. This allows
+ * changing compression algorithms without invalidating hashes.
+ */
+export function compressArchive(tarBytes: Uint8Array): Uint8Array {
+  const buffer = new ArrayBuffer(tarBytes.byteLength)
+  new Uint8Array(buffer).set(tarBytes)
+  return Bun.gzipSync(buffer)
+}

package/src/build/detect-collisions.ts

@@ -0,0 +1,36 @@
+import type { FacetManifest } from '../schemas/facet-manifest.ts'
+import type { ValidationError } from '../types.ts'
+
+type AssetType = 'skill' | 'agent' | 'command'
+
+/**
+ * Detects naming collisions within each asset type.
+ * Skills must have unique names within skills, agents within agents,
+ * and commands within commands. Cross-type duplicates are allowed —
+ * a skill and an agent may share the same name.
+ */
+export function detectNamingCollisions(manifest: FacetManifest): ValidationError[] {
+  const errors: ValidationError[] = []
+
+  const checkDuplicates = (names: string[], type: AssetType) => {
+    const seen = new Set<string>()
+    for (const name of names) {
+      if (seen.has(name)) {
+        errors.push({
+          path: name,
+          message: `Naming collision: "${name}" is declared more than once in ${type}s`,
+          expected: `unique name within ${type}s`,
+          actual: `"${name}" appears multiple times in ${type}s`,
+        })
+      } else {
+        seen.add(name)
+      }
+    }
+  }
+
+  if (manifest.skills) checkDuplicates(Object.keys(manifest.skills), 'skill')
+  if (manifest.agents) checkDuplicates(Object.keys(manifest.agents), 'agent')
+  if (manifest.commands) checkDuplicates(Object.keys(manifest.commands), 'command')
+
+  return errors
+}

package/src/build/pipeline.ts

@@ -0,0 +1,120 @@
+import { join } from 'node:path'
+import { FACET_MANIFEST_FILE, loadManifest, type ResolvedFacetManifest, resolvePrompts } from '../loaders/facet.ts'
+import type { ValidationError } from '../types.ts'
+import {
+  assembleTar,
+  collectArchiveEntries,
+  compressArchive,
+  computeAssetHashes,
+  computeContentHash,
+} from './content-hash.ts'
+import { detectNamingCollisions } from './detect-collisions.ts'
+import { validateCompactFacets } from './validate-facets.ts'
+import { validatePlatformConfigs } from './validate-platforms.ts'
+
+export interface BuildProgress {
+  stage: string
+  status: 'running' | 'done' | 'failed'
+}
+
+export interface BuildResult {
+  ok: true
+  data: ResolvedFacetManifest
+  warnings: string[]
+  archiveBytes: Uint8Array
+  integrity: string
+  archiveFilename: string
+  assetHashes: Record<string, string>
+}
+
+export interface BuildFailure {
+  ok: false
+  errors: ValidationError[]
+  warnings: string[]
+}
+
+/**
+ * Runs the full build pipeline:
+ * 1. Load manifest — read the facet manifest, parse JSON, validate schema, check constraints
+ * 2. Resolve prompts — read prompt files at conventional paths for skills, agents, commands (also verifies files exist)
+ * 3. Validate compact facets format — check name@version pattern
+ * 4. Detect naming collisions — fail if same name used within an asset type
+ * 5. Validate platform config — check known platform schemas, warn on unknown
+ * 6. Assemble archive — collect entries, compute per-asset hashes, build deterministic tar, compute integrity hash, compress for delivery
+ *
+ * Returns the resolved manifest and archive data on success, or collected errors on failure.
+ * Warnings are returned in both cases.
+ *
+ * An optional `onProgress` callback receives stage updates for UI display.
+ */
+export async function runBuildPipeline(
+  rootDir: string,
+  onProgress?: (progress: BuildProgress) => void,
+): Promise<BuildResult | BuildFailure> {
+  const warnings: string[] = []
+
+  // Stage 1: Load manifest
+  onProgress?.({ stage: 'Validating manifest', status: 'running' })
+
+  const loadResult = await loadManifest(rootDir)
+  if (!loadResult.ok) {
+    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
+    return { ok: false, errors: loadResult.errors, warnings }
+  }
+  const manifest = loadResult.data
+
+  // Stage 2: Resolve prompts (also serves as file existence verification)
+  const resolveResult = await resolvePrompts(manifest, rootDir)
+  if (!resolveResult.ok) {
+    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
+    return { ok: false, errors: resolveResult.errors, warnings }
+  }
+
+  // Stage 3: Validate compact facets format
+  const facetsErrors = validateCompactFacets(manifest)
+  if (facetsErrors.length > 0) {
+    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
+    return { ok: false, errors: facetsErrors, warnings }
+  }
+
+  // Stage 4: Detect naming collisions
+  const collisionErrors = detectNamingCollisions(manifest)
+  if (collisionErrors.length > 0) {
+    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
+    return { ok: false, errors: collisionErrors, warnings }
+  }
+
+  // Stage 5: Validate platform config
+  const platformResult = validatePlatformConfigs(manifest)
+  if (platformResult.errors.length > 0) {
+    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
+    return { ok: false, errors: platformResult.errors, warnings: [...warnings, ...platformResult.warnings] }
+  }
+  warnings.push(...platformResult.warnings)
+
+  onProgress?.({ stage: 'Validating manifest', status: 'done' })
+
+  // Stage 6: Assemble archive, compute content hashes, and compress for delivery
+  onProgress?.({ stage: 'Assembling archive', status: 'running' })
+
+  const resolved = resolveResult.data
+  const manifestContent = await Bun.file(join(rootDir, FACET_MANIFEST_FILE)).text()
+  const entries = collectArchiveEntries(resolved, manifestContent)
+  const assetHashes = computeAssetHashes(entries)
+  const tarBytes = assembleTar(entries)
+  const integrity = computeContentHash(tarBytes)
+  const archiveBytes = compressArchive(tarBytes)
+  const archiveFilename = `${resolved.name}-${resolved.version}.facet`
+
+  onProgress?.({ stage: 'Assembling archive', status: 'done' })
+
+  return {
+    ok: true,
+    data: resolved,
+    warnings,
+    archiveBytes,
+    integrity,
+    archiveFilename,
+    assetHashes,
+  }
+}

package/src/build/validate-facets.ts

@@ -0,0 +1,34 @@
+import type { FacetManifest } from '../schemas/facet-manifest.ts'
+import type { ValidationError } from '../types.ts'
+
+/**
+ * Pattern for compact facets entries: "name@version" or "@scope/name@version".
+ * The last `@` before a non-empty version string is the separator.
+ */
+const COMPACT_FACETS_PATTERN = /^(@?[^@]+)@(.+)$/
+
+/**
+ * Validates compact facets entries conform to the "name@version" format.
+ * Selective (object) entries are skipped — they have their own structural validation.
+ */
+export function validateCompactFacets(manifest: FacetManifest): ValidationError[] {
+  const errors: ValidationError[] = []
+
+  if (!manifest.facets) return errors
+
+  for (let i = 0; i < manifest.facets.length; i++) {
+    const entry = manifest.facets[i]
+    if (typeof entry !== 'string') continue
+
+    if (!COMPACT_FACETS_PATTERN.test(entry)) {
+      errors.push({
+        path: `facets[${i}]`,
+        message: `Compact facets entry "${entry}" does not match the expected "name@version" format`,
+        expected: '"name@version" or "@scope/name@version"',
+        actual: entry,
+      })
+    }
+  }
+
+  return errors
+}