@agent-facets/core 0.1.1

package/src/__tests__/content-hash.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, test } from 'bun:test'
+import { parseTar, parseTarGzip } from 'nanotar'
+import {
+  assembleTar,
+  collectArchiveEntries,
+  compressArchive,
+  computeAssetHashes,
+  computeContentHash,
+} from '../build/content-hash.ts'
+import type { ResolvedFacetManifest } from '../loaders/facet.ts'
+
+describe('computeContentHash', () => {
+  test('computes correct SHA-256 for string input', () => {
+    const hash = computeContentHash('hello world')
+    expect(hash).toMatchInlineSnapshot(`"sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"`)
+  })
+
+  test('computes correct SHA-256 for Uint8Array input', () => {
+    const hash = computeContentHash(new TextEncoder().encode('hello world'))
+    expect(hash).toMatchInlineSnapshot(`"sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"`)
+  })
+
+  test('identical content produces identical hashes', () => {
+    const hash1 = computeContentHash('identical content')
+    const hash2 = computeContentHash('identical content')
+    expect(hash1).toMatchInlineSnapshot(`"sha256:15bbe85aac4518db7da507997bd8b9baa07ddea5d0a08d098f85f1bf08c02521"`)
+    expect(hash2).toBe(hash1)
+  })
+
+  test('different content produces different hashes', () => {
+    const hash1 = computeContentHash('content A')
+    const hash2 = computeContentHash('content B')
+    expect(hash1).toMatchInlineSnapshot(`"sha256:49114a9a2b7d46ec27be62ae3eade12f78d46cf5a99c52cd4f80381d723eed6e"`)
+    expect(hash2).toMatchInlineSnapshot(`"sha256:d27a54dc662fff702c2183d536e87414d5fe6fc072f6bc270b01a34f6de265bc"`)
+  })
+
+  test('string and Uint8Array of same content produce same hash', () => {
+    const content = 'same content'
+    const hashStr = computeContentHash(content)
+    const hashBytes = computeContentHash(new TextEncoder().encode(content))
+    expect(hashStr).toMatchInlineSnapshot(`"sha256:a636bd7cd42060a4d07fa1bfbcc010eb7794c2ba721e1e3e4c20335a15b66eaf"`)
+    expect(hashBytes).toBe(hashStr)
+  })
+})
+
+describe('collectArchiveEntries', () => {
+  test('collects manifest and all asset types', () => {
+    const resolved: ResolvedFacetManifest = {
+      name: 'test',
+      version: '1.0.0',
+      skills: {
+        review: { description: 'Review skill', prompt: '# Review' },
+      },
+      agents: {
+        helper: { description: 'Helper agent', prompt: '# Helper' },
+      },
+      commands: {
+        deploy: { description: 'Deploy command', prompt: '# Deploy' },
+      },
+    }
+
+    const entries = collectArchiveEntries(resolved, '{"name":"test","version":"1.0.0"}')
+
+    expect(entries).toHaveLength(4)
+    expect(entries.map((e) => e.path)).toContain('facet.json')
+    expect(entries.map((e) => e.path)).toContain('skills/review.md')
+    expect(entries.map((e) => e.path)).toContain('agents/helper.md')
+    expect(entries.map((e) => e.path)).toContain('commands/deploy.md')
+  })
+
+  test('entries are sorted lexicographically by path', () => {
+    const resolved: ResolvedFacetManifest = {
+      name: 'test',
+      version: '1.0.0',
+      skills: {
+        'z-skill': { description: 'Z', prompt: '# Z' },
+        'a-skill': { description: 'A', prompt: '# A' },
+      },
+      agents: {
+        'b-agent': { description: 'B', prompt: '# B' },
+      },
+    }
+
+    const entries = collectArchiveEntries(resolved, 'manifest content')
+    const paths = entries.map((e) => e.path)
+
+    expect(paths).toEqual(['agents/b-agent.md', 'facet.json', 'skills/a-skill.md', 'skills/z-skill.md'])
+  })
+
+  test('handles manifest with no optional asset types', () => {
+    const resolved: ResolvedFacetManifest = {
+      name: 'minimal',
+      version: '0.1.0',
+      skills: {
+        only: { description: 'Only skill', prompt: '# Only' },
+      },
+    }
+
+    const entries = collectArchiveEntries(resolved, 'manifest')
+    expect(entries).toHaveLength(2)
+  })
+})
+
+describe('computeAssetHashes', () => {
+  test('returns correct hash for each entry', () => {
+    const entries = [
+      { path: 'facet.json', content: '{"name":"test"}' },
+      { path: 'skills/review.md', content: '# Review' },
+    ]
+
+    const hashes = computeAssetHashes(entries)
+
+    expect(Object.keys(hashes)).toHaveLength(2)
+    expect(hashes['facet.json']).toMatchInlineSnapshot(
+      `"sha256:7d9fd2051fc32b32feab10946fab6bb91426ab7e39aa5439289ed892864aa91d"`,
+    )
+    expect(hashes['skills/review.md']).toMatchInlineSnapshot(
+      `"sha256:f1a9d9d60fba2e67d82d788760d147d95461a58456411e205bf33a6dbdc3497f"`,
+    )
+  })
+
+  test('hash matches computeContentHash for same content', () => {
+    const entries = [{ path: 'test.md', content: 'test content' }]
+
+    const hashes = computeAssetHashes(entries)
+
+    expect(hashes['test.md']).toMatchInlineSnapshot(
+      `"sha256:6ae8a75555209fd6c44157c0aed8016e763ff435a19cf186f76863140143ff72"`,
+    )
+  })
+})
+
+describe('assembleTar', () => {
+  test('produces a valid tar archive', () => {
+    const entries = [
+      { path: 'facet.json', content: '{"name":"test","version":"1.0.0"}' },
+      { path: 'skills/review.md', content: '# Review skill' },
+    ]
+
+    const tar = assembleTar(entries)
+
+    expect(tar).toBeInstanceOf(Uint8Array)
+    expect(tar.length).toBeGreaterThan(0)
+
+    const parsed = parseTar(tar)
+    expect(parsed).toHaveLength(2)
+
+    const names = parsed.map((f) => f.name)
+    expect(names).toContain('facet.json')
+    expect(names).toContain('skills/review.md')
+  })
+
+  test('tar contains correct file contents', () => {
+    const entries = [{ path: 'test.md', content: 'hello world' }]
+
+    const tar = assembleTar(entries)
+    const parsed = parseTar(tar)
+
+    expect(parsed[0]?.text).toBe('hello world')
+  })
+
+  test('produces deterministic output — same input yields identical bytes', () => {
+    const entries = [
+      { path: 'a.md', content: 'content A' },
+      { path: 'b.md', content: 'content B' },
+    ]
+
+    const tar1 = assembleTar(entries)
+    const tar2 = assembleTar(entries)
+
+    expect(tar1.length).toBe(tar2.length)
+    expect(Buffer.from(tar1).equals(Buffer.from(tar2))).toBe(true)
+  })
+
+  test('deterministic tar produces stable hash', () => {
+    const entries = [
+      { path: 'a.md', content: 'content A' },
+      { path: 'b.md', content: 'content B' },
+    ]
+
+    const tar1 = assembleTar(entries)
+    const tar2 = assembleTar(entries)
+    const hash1 = computeContentHash(tar1)
+    const hash2 = computeContentHash(tar2)
+
+    expect(hash1).toMatch(/^sha256:[a-f0-9]{64}$/)
+    expect(hash1).toBe(hash2)
+  })
+
+  test('tar hash changes when content changes', () => {
+    const entries1 = [{ path: 'test.md', content: 'version 1' }]
+    const entries2 = [{ path: 'test.md', content: 'version 2' }]
+
+    const tar1 = assembleTar(entries1)
+    const tar2 = assembleTar(entries2)
+
+    const hash1 = computeContentHash(tar1)
+    const hash2 = computeContentHash(tar2)
+
+    expect(hash1).not.toBe(hash2)
+  })
+})
+
+describe('compressArchive', () => {
+  test('compressed archive can be decompressed to recover original tar', async () => {
+    const entries = [
+      { path: 'facet.json', content: '{"name":"test","version":"1.0.0"}' },
+      { path: 'skills/review.md', content: '# Review skill' },
+    ]
+
+    const tar = assembleTar(entries)
+    const compressed = compressArchive(tar)
+
+    expect(compressed.length).toBeGreaterThan(0)
+    expect(compressed.length).toBeLessThan(tar.length) // gzip should compress text content
+
+    // Decompress and verify contents survive the round-trip
+    const parsed = await parseTarGzip(compressed)
+    expect(parsed).toHaveLength(2)
+
+    const names = parsed.map((f) => f.name)
+    expect(names).toContain('facet.json')
+    expect(names).toContain('skills/review.md')
+    expect(parsed.find((f) => f.name === 'skills/review.md')?.text).toBe('# Review skill')
+  })
+})

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

@@ -0,0 +1,264 @@
+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 { loadManifest, resolvePrompts } from '../loaders/facet.ts'
+
+let testDir: string
+
+beforeAll(async () => {
+  testDir = await mkdtemp(join(tmpdir(), 'facet-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'), '') // ensure dir exists
+  return dir
+}
+
+// --- loadManifest ---
+
+describe('loadManifest', () => {
+  test('successful load', async () => {
+    const dir = await createFixtureDir('valid')
+    await writeFixture(
+      dir,
+      'facet.json',
+      JSON.stringify({
+        name: 'test-facet',
+        version: '1.0.0',
+        skills: {
+          'code-review': {
+            description: 'Reviews code for issues',
+          },
+        },
+      }),
+    )
+
+    const result = await loadManifest(dir)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.name).toBe('test-facet')
+      expect(result.data.version).toBe('1.0.0')
+      expect(result.data.skills?.['code-review']?.description).toBe('Reviews code for issues')
+    }
+  })
+
+  test('file not found', async () => {
+    const dir = await createFixtureDir('missing')
+
+    const result = await loadManifest(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')
+    await writeFixture(dir, 'facet.json', '{ "name": [unterminated')
+
+    const result = await loadManifest(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors).toHaveLength(1)
+      expect(result.errors.at(0)?.message).toContain('JSON syntax error')
+    }
+  })
+
+  test('schema validation errors with correct paths', async () => {
+    const dir = await createFixtureDir('schema-error')
+    await writeFixture(
+      dir,
+      'facet.json',
+      JSON.stringify({
+        name: 'test-facet',
+        version: '1.0.0',
+        agents: {
+          reviewer: {
+            // missing required description
+          },
+        },
+      }),
+    )
+
+    const result = await loadManifest(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      const descriptionError = result.errors.find((e) => e.path.includes('description'))
+      expect(descriptionError).toBeDefined()
+    }
+  })
+
+  test('no text assets → business-rule error', async () => {
+    const dir = await createFixtureDir('no-text')
+    await writeFixture(
+      dir,
+      'facet.json',
+      JSON.stringify({
+        name: 'empty-facet',
+        version: '1.0.0',
+        servers: {
+          jira: '1.0.0',
+        },
+      }),
+    )
+
+    const result = await loadManifest(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors.at(0)?.message).toContain('at least one text asset')
+    }
+  })
+
+  test('full manifest loads successfully', async () => {
+    const dir = await createFixtureDir('full')
+    await writeFixture(
+      dir,
+      'facet.json',
+      JSON.stringify({
+        name: 'acme-dev',
+        version: '1.0.0',
+        description: 'Acme dev toolkit',
+        author: 'acme-org',
+        skills: {
+          'code-standards': {
+            description: 'Org coding standards',
+          },
+        },
+        agents: {
+          reviewer: {
+            description: 'Code reviewer',
+          },
+        },
+        commands: {
+          review: {
+            description: 'Run review',
+          },
+        },
+        facets: ['base@1.0.0'],
+        servers: {
+          jira: '1.0.0',
+          slack: {
+            image: 'ghcr.io/acme/slack-bot:v2',
+          },
+        },
+      }),
+    )
+
+    const result = await loadManifest(dir)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.name).toBe('acme-dev')
+      expect(result.data.agents?.reviewer?.description).toBe('Code reviewer')
+      expect(result.data.servers?.slack).toEqual({
+        image: 'ghcr.io/acme/slack-bot:v2',
+      })
+    }
+  })
+})
+
+// --- resolvePrompts ---
+
+describe('resolvePrompts', () => {
+  test('prompt content is resolved from conventional file paths', async () => {
+    const dir = await createFixtureDir('resolve-convention')
+    await writeFixture(dir, 'skills/review.md', '# Code Review\nReview all code.')
+    await writeFixture(dir, 'agents/reviewer.md', '# Reviewer\nReview this code.')
+    await writeFixture(dir, 'commands/deploy.md', '# Deploy\nDeploy the code.')
+
+    const manifest = {
+      name: 'test',
+      version: '1.0.0',
+      skills: {
+        review: { description: 'A review skill' },
+      },
+      agents: {
+        reviewer: { description: 'A reviewer agent' },
+      },
+      commands: {
+        deploy: { description: 'A deploy command' },
+      },
+    }
+
+    const result = await resolvePrompts(manifest, dir)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.skills?.review?.prompt).toBe('# Code Review\nReview all code.')
+      expect(result.data.agents?.reviewer?.prompt).toBe('# Reviewer\nReview this code.')
+      expect(result.data.commands?.deploy?.prompt).toBe('# Deploy\nDeploy the code.')
+    }
+  })
+
+  test('file-based prompt is resolved from agents/<name>.md', async () => {
+    const dir = await createFixtureDir('resolve-file')
+    await writeFixture(dir, 'agents/reviewer.md', '# Review\nCheck all code.')
+
+    const manifest = {
+      name: 'test',
+      version: '1.0.0',
+      agents: {
+        reviewer: { description: 'A reviewer' },
+      },
+    }
+
+    const result = await resolvePrompts(manifest, dir)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.agents?.reviewer?.prompt).toBe('# Review\nCheck all code.')
+    }
+  })
+
+  test('missing prompt file reports error with asset name', async () => {
+    const dir = await createFixtureDir('resolve-missing')
+
+    const manifest = {
+      name: 'test',
+      version: '1.0.0',
+      agents: {
+        reviewer: { description: 'A reviewer' },
+      },
+    }
+
+    const result = await resolvePrompts(manifest, dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors).toHaveLength(1)
+      expect(result.errors.at(0)?.path).toBe('agents.reviewer')
+      expect(result.errors.at(0)?.message).toContain('agents/reviewer.md')
+    }
+  })
+
+  test('manifest without agents or commands resolves successfully', async () => {
+    const dir = await createFixtureDir('resolve-skills-only')
+    await writeFixture(dir, 'skills/x.md', '# Skill X\nDo x.')
+
+    const manifest = {
+      name: 'test',
+      version: '1.0.0',
+      skills: {
+        x: {
+          description: 'A skill',
+        },
+      },
+    }
+
+    const result = await resolvePrompts(manifest, dir)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.name).toBe('test')
+      expect(result.data.skills?.x?.prompt).toBe('# Skill X\nDo x.')
+    }
+  })
+})

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

@@ -0,0 +1,208 @@
+import { describe, expect, test } from 'bun:test'
+import { type } from 'arktype'
+import { checkFacetManifestConstraints, type FacetManifest, FacetManifestSchema } from '../schemas/facet-manifest.ts'
+
+// --- Valid manifests ---
+
+describe('FacetManifestSchema — valid manifests', () => {
+  test('minimal manifest with a skill', () => {
+    const input = {
+      name: 'my-facet',
+      version: '1.0.0',
+      skills: {
+        'code-review': {
+          description: 'Reviews code for issues',
+        },
+      },
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as FacetManifest
+    expect(data.name).toBe('my-facet')
+    expect(data.version).toBe('1.0.0')
+    expect(data.skills?.['code-review']?.description).toBe('Reviews code for issues')
+  })
+
+  test('full manifest with all sections', () => {
+    const input = {
+      name: 'acme-dev',
+      version: '1.0.0',
+      description: 'Acme developer toolkit',
+      author: 'acme-org',
+      skills: {
+        'code-standards': {
+          description: 'Org coding standards',
+        },
+        'pr-template': {
+          description: 'PR template guidelines',
+        },
+      },
+      agents: {
+        reviewer: {
+          description: 'Org code reviewer',
+          platforms: {
+            opencode: { tools: { grep: true, bash: true } },
+          },
+        },
+        'quick-check': {
+          description: 'Fast lint check',
+        },
+      },
+      commands: {
+        review: {
+          description: 'Run a code review',
+        },
+      },
+      facets: [
+        'code-review-base@1.0.0',
+        {
+          name: 'typescript-patterns',
+          version: '2.1.0',
+          skills: ['ts-conventions', 'any-usage'],
+        },
+      ],
+      servers: {
+        jira: '1.0.0',
+        github: '2.3.0',
+        '@acme/deploy': '0.5.0',
+        slack: { image: 'ghcr.io/acme/slack-bot:v2' },
+      },
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as FacetManifest
+    expect(data.name).toBe('acme-dev')
+    expect(data.agents?.reviewer?.description).toBe('Org code reviewer')
+    expect(data.agents?.['quick-check']?.description).toBe('Fast lint check')
+    expect(data.servers?.jira).toBe('1.0.0')
+    expect(data.servers?.slack).toEqual({
+      image: 'ghcr.io/acme/slack-bot:v2',
+    })
+  })
+
+  test('manifest with only composed facets is valid', () => {
+    const input = {
+      name: 'composed-only',
+      version: '1.0.0',
+      facets: ['base@1.0.0'],
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as FacetManifest
+    const errors = checkFacetManifestConstraints(data)
+    expect(errors).toHaveLength(0)
+  })
+})
+
+// --- Invalid manifests ---
+
+describe('FacetManifestSchema — invalid manifests', () => {
+  test('missing name', () => {
+    const input = { version: '1.0.0', skills: { x: { description: 'A skill' } } }
+    const result = FacetManifestSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+  })
+
+  test('missing version', () => {
+    const input = { name: 'my-facet', skills: { x: { description: 'A skill' } } }
+    const result = FacetManifestSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+  })
+
+  test('agent missing description', () => {
+    const input = {
+      name: 'my-facet',
+      version: '1.0.0',
+      agents: {
+        reviewer: { platforms: { opencode: {} } },
+      },
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+    const errors = result as InstanceType<typeof type.errors>
+    expect(errors.some((e) => e.path.includes('reviewer') && e.path.includes('description'))).toBe(true)
+  })
+
+  test('server reference object without image field', () => {
+    const input = {
+      name: 'my-facet',
+      version: '1.0.0',
+      skills: { x: { description: 'A skill' } },
+      servers: {
+        bad: { notImage: 'ghcr.io/something' },
+      },
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).toBeInstanceOf(type.errors)
+    const errors = result as InstanceType<typeof type.errors>
+    expect(errors.some((e) => e.path.includes('bad'))).toBe(true)
+  })
+})
+
+// --- Business-rule constraints ---
+
+describe('checkFacetManifestConstraints', () => {
+  test('no text assets → error', () => {
+    const input = {
+      name: 'empty',
+      version: '1.0.0',
+      servers: { jira: '1.0.0' },
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const errors = checkFacetManifestConstraints(result as FacetManifest)
+    expect(errors).toHaveLength(1)
+    const firstError = errors[0]
+    expect(firstError).toBeDefined()
+    expect(firstError?.message).toContain('at least one text asset')
+  })
+
+  test('selective facets entry with no asset selection → error', () => {
+    const input = {
+      name: 'bad-selective',
+      version: '1.0.0',
+      facets: [{ name: 'other', version: '1.0.0' }],
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const errors = checkFacetManifestConstraints(result as FacetManifest)
+    const selectiveError = errors.find((e) => e.message.includes('at least one asset type'))
+    expect(selectiveError).toBeDefined()
+    expect(selectiveError?.path).toBe('facets[0]')
+  })
+})
+
+// --- Unknown field pass-through ---
+
+describe('FacetManifestSchema — unknown field tolerance', () => {
+  test('top-level unknown field is preserved', () => {
+    const input = {
+      name: 'my-facet',
+      version: '1.0.0',
+      skills: { x: { description: 'A skill' } },
+      license: 'MIT',
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as FacetManifest & { license: string }
+    expect(data.license).toBe('MIT')
+  })
+
+  test('unknown field nested in agent descriptor is preserved', () => {
+    const input = {
+      name: 'my-facet',
+      version: '1.0.0',
+      agents: {
+        reviewer: {
+          description: 'A reviewer agent',
+          model: 'claude-sonnet',
+        },
+      },
+    }
+    const result = FacetManifestSchema(input)
+    expect(result).not.toBeInstanceOf(type.errors)
+    const data = result as Record<string, unknown>
+    const agents = data.agents as Record<string, Record<string, unknown>> | undefined
+    expect(agents?.reviewer?.model).toBe('claude-sonnet')
+  })
+})