@yolk-sdk/skillset 0.0.1-canary.0

package/dist/name.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.mjs","names":[],"sources":["../src/name.ts"],"sourcesContent":["import { Effect } from 'effect'\nimport { SkillsetError } from './errors.ts'\n\nconst skillsetNamePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/\nconst maxSkillsetNameLength = 64\n\nexport const isValidSkillsetName = (name: string) =>\n  name.length > 0 && name.length <= maxSkillsetNameLength && skillsetNamePattern.test(name)\n\nexport const validateSkillsetName = (name: string) =>\n  isValidSkillsetName(name)\n    ? Effect.succeed(name)\n    : Effect.fail(\n        new SkillsetError({\n          cause: 'invalid_name',\n          message: `Invalid skillset entry name: ${name}`\n        })\n      )\n\nexport const validateDirectoryName = (expected: string, actual: string) =>\n  expected === actual\n    ? Effect.succeed(expected)\n    : Effect.fail(\n        new SkillsetError({\n          cause: 'name_mismatch',\n          message: `Skill name must match directory name: expected ${expected}, got ${actual}`\n        })\n      )\n"],"mappings":";;;AAGA,MAAM,sBAAsB;AAC5B,MAAM,wBAAwB;AAE9B,MAAa,uBAAuB,SAClC,KAAK,SAAS,KAAK,KAAK,UAAU,yBAAyB,oBAAoB,KAAK,IAAI;AAE1F,MAAa,wBAAwB,SACnC,oBAAoB,IAAI,IACpB,OAAO,QAAQ,IAAI,IACnB,OAAO,KACL,IAAI,cAAc;CAChB,OAAO;CACP,SAAS,gCAAgC;AAC3C,CAAC,CACH;AAEN,MAAa,yBAAyB,UAAkB,WACtD,aAAa,SACT,OAAO,QAAQ,QAAQ,IACvB,OAAO,KACL,IAAI,cAAc;CAChB,OAAO;CACP,SAAS,kDAAkD,SAAS,QAAQ;AAC9E,CAAC,CACH"}

package/dist/skill.d.mts

@@ -0,0 +1,30 @@
+import { SkillsetError } from "./errors.mjs";
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+
+//#region src/skill.d.ts
+declare const SkillInfo: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly description: Schema.String;
+  readonly location: Schema.String;
+  readonly content: Schema.String;
+  readonly source: Schema.optional<Schema.String>;
+}>;
+type SkillInfo = typeof SkillInfo.Type;
+type ParseSkillInput = {
+  readonly markdown: string;
+  readonly location: string;
+  readonly directoryName?: string;
+  readonly source?: string;
+};
+declare const parseSkillMarkdown: (input: ParseSkillInput) => Effect.Effect<{
+  name: string;
+  description: string;
+  location: string;
+  content: string;
+  source: string | undefined;
+}, SkillsetError, never>;
+declare const formatAvailableSkills: (skills: ReadonlyArray<SkillInfo>) => string;
+//#endregion
+export { ParseSkillInput, SkillInfo, formatAvailableSkills, parseSkillMarkdown };
+//# sourceMappingURL=skill.d.mts.map

package/dist/skill.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.mts","names":[],"sources":["../src/skill.ts"],"mappings":";;;;;cAMa,SAAA,EAAS,MAAA,CAAA,MAAA;EAAA;;;;;;KAOV,SAAA,UAAmB,SAAA,CAAU,IAAI;AAAA,KAEjC,eAAA;EAAA,SACD,QAAA;EAAA,SACA,QAAA;EAAA,SACA,aAAA;EAAA,SACA,MAAA;AAAA;AAAA,cAgBE,kBAAA,GAAsB,KAAA,EAAO,eAAA,KAAe,MAAA,CAAA,MAAA;;;;;;;cAqB5C,qBAAA,GAAyB,MAAA,EAAQ,aAAa,CAAC,SAAA"}

package/dist/skill.mjs

@@ -0,0 +1,47 @@
+import { SkillsetError } from "./errors.mjs";
+import { parseMarkdownDocument } from "./markdown.mjs";
+import { validateDirectoryName, validateSkillsetName } from "./name.mjs";
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+//#region src/skill.ts
+const SkillInfo = Schema.Struct({
+	name: Schema.String,
+	description: Schema.String,
+	location: Schema.String,
+	content: Schema.String,
+	source: Schema.optional(Schema.String)
+});
+const requiredField = (data, field) => {
+	const value = data[field];
+	return value === void 0 || value.length === 0 ? Effect.fail(new SkillsetError({
+		cause: "frontmatter_field_missing",
+		message: `Skill frontmatter requires ${field}`
+	})) : Effect.succeed(value);
+};
+const parseSkillMarkdown = (input) => Effect.gen(function* () {
+	const document = yield* parseMarkdownDocument(input.markdown);
+	const name = yield* requiredField(document.data, "name").pipe(Effect.flatMap(validateSkillsetName));
+	const description = yield* requiredField(document.data, "description");
+	if (input.directoryName !== void 0) yield* validateDirectoryName(input.directoryName, name);
+	return {
+		name,
+		description,
+		location: input.location,
+		content: document.content,
+		source: input.source
+	};
+});
+const formatAvailableSkills = (skills) => skills.length === 0 ? "" : [
+	"<available_skills>",
+	...skills.slice().sort((a, b) => a.name.localeCompare(b.name)).flatMap((skill) => [
+		"  <skill>",
+		`    <name>${skill.name}</name>`,
+		`    <description>${skill.description}</description>`,
+		"  </skill>"
+	]),
+	"</available_skills>"
+].join("\n");
+//#endregion
+export { SkillInfo, formatAvailableSkills, parseSkillMarkdown };
+
+//# sourceMappingURL=skill.mjs.map

package/dist/skill.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.mjs","names":[],"sources":["../src/skill.ts"],"sourcesContent":["import { Effect } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport { SkillsetError } from './errors.ts'\nimport { parseMarkdownDocument } from './markdown.ts'\nimport { validateDirectoryName, validateSkillsetName } from './name.ts'\n\nexport const SkillInfo = Schema.Struct({\n  name: Schema.String,\n  description: Schema.String,\n  location: Schema.String,\n  content: Schema.String,\n  source: Schema.optional(Schema.String)\n})\nexport type SkillInfo = typeof SkillInfo.Type\n\nexport type ParseSkillInput = {\n  readonly markdown: string\n  readonly location: string\n  readonly directoryName?: string\n  readonly source?: string\n}\n\nconst requiredField = (data: Readonly<Record<string, string>>, field: string) => {\n  const value = data[field]\n\n  return value === undefined || value.length === 0\n    ? Effect.fail(\n        new SkillsetError({\n          cause: 'frontmatter_field_missing',\n          message: `Skill frontmatter requires ${field}`\n        })\n      )\n    : Effect.succeed(value)\n}\n\nexport const parseSkillMarkdown = (input: ParseSkillInput) =>\n  Effect.gen(function* () {\n    const document = yield* parseMarkdownDocument(input.markdown)\n    const name = yield* requiredField(document.data, 'name').pipe(\n      Effect.flatMap(validateSkillsetName)\n    )\n    const description = yield* requiredField(document.data, 'description')\n\n    if (input.directoryName !== undefined) {\n      yield* validateDirectoryName(input.directoryName, name)\n    }\n\n    return {\n      name,\n      description,\n      location: input.location,\n      content: document.content,\n      source: input.source\n    }\n  })\n\nexport const formatAvailableSkills = (skills: ReadonlyArray<SkillInfo>) =>\n  skills.length === 0\n    ? ''\n    : [\n        '<available_skills>',\n        ...skills\n          .slice()\n          .sort((a, b) => a.name.localeCompare(b.name))\n          .flatMap(skill => [\n            '  <skill>',\n            `    <name>${skill.name}</name>`,\n            `    <description>${skill.description}</description>`,\n            '  </skill>'\n          ]),\n        '</available_skills>'\n      ].join('\\n')\n"],"mappings":";;;;;;AAMA,MAAa,YAAY,OAAO,OAAO;CACrC,MAAM,OAAO;CACb,aAAa,OAAO;CACpB,UAAU,OAAO;CACjB,SAAS,OAAO;CAChB,QAAQ,OAAO,SAAS,OAAO,MAAM;AACvC,CAAC;AAUD,MAAM,iBAAiB,MAAwC,UAAkB;CAC/E,MAAM,QAAQ,KAAK;CAEnB,OAAO,UAAU,KAAA,KAAa,MAAM,WAAW,IAC3C,OAAO,KACL,IAAI,cAAc;EAChB,OAAO;EACP,SAAS,8BAA8B;CACzC,CAAC,CACH,IACA,OAAO,QAAQ,KAAK;AAC1B;AAEA,MAAa,sBAAsB,UACjC,OAAO,IAAI,aAAa;CACtB,MAAM,WAAW,OAAO,sBAAsB,MAAM,QAAQ;CAC5D,MAAM,OAAO,OAAO,cAAc,SAAS,MAAM,MAAM,EAAE,KACvD,OAAO,QAAQ,oBAAoB,CACrC;CACA,MAAM,cAAc,OAAO,cAAc,SAAS,MAAM,aAAa;CAErE,IAAI,MAAM,kBAAkB,KAAA,GAC1B,OAAO,sBAAsB,MAAM,eAAe,IAAI;CAGxD,OAAO;EACL;EACA;EACA,UAAU,MAAM;EAChB,SAAS,SAAS;EAClB,QAAQ,MAAM;CAChB;AACF,CAAC;AAEH,MAAa,yBAAyB,WACpC,OAAO,WAAW,IACd,KACA;CACE;CACA,GAAG,OACA,MAAM,EACN,MAAM,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC,EAC3C,SAAQ,UAAS;EAChB;EACA,aAAa,MAAM,KAAK;EACxB,oBAAoB,MAAM,YAAY;EACtC;CACF,CAAC;CACH;AACF,EAAE,KAAK,IAAI"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@yolk-sdk/skillset",
+  "version": "0.0.1-canary.0",
+  "description": "Portable skill and slash-command parsing and catalog primitives for Yolk.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magoz/yolk-sdk.git",
+    "directory": "packages/skillset"
+  },
+  "bugs": {
+    "url": "https://github.com/magoz/yolk-sdk/issues"
+  },
+  "homepage": "https://github.com/magoz/yolk-sdk#readme",
+  "keywords": [
+    "skills",
+    "commands",
+    "agents",
+    "effect"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "dist/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.65"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:run": "vitest run --passWithNoTests"
+  }
+}

package/src/command.ts

@@ -0,0 +1,196 @@
+import { Effect } from 'effect'
+import * as Schema from 'effect/Schema'
+import { SkillsetError } from './errors.ts'
+import { parseMarkdownDocument } from './markdown.ts'
+import { validateSkillsetName } from './name.ts'
+
+export const CommandArgument = Schema.Struct({
+  name: Schema.String,
+  required: Schema.Boolean,
+  description: Schema.optional(Schema.String)
+})
+export type CommandArgument = typeof CommandArgument.Type
+
+export const CommandAccess = Schema.Union([
+  Schema.Literal('read'),
+  Schema.Literal('write'),
+  Schema.Literal('destructive')
+])
+export type CommandAccess = typeof CommandAccess.Type
+
+export const CommandInfo = Schema.Struct({
+  name: Schema.String,
+  description: Schema.optional(Schema.String),
+  template: Schema.String,
+  hints: Schema.Array(Schema.String),
+  arguments: Schema.optional(Schema.Array(CommandArgument)),
+  access: Schema.optional(CommandAccess),
+  fileRefs: Schema.optional(Schema.Boolean),
+  location: Schema.optional(Schema.String),
+  source: Schema.optional(Schema.String)
+})
+export type CommandInfo = typeof CommandInfo.Type
+
+export type ParseCommandInput = {
+  readonly markdown: string
+  readonly name: string
+  readonly location?: string
+  readonly source?: string
+}
+
+const numberedPlaceholderPattern = /\$(\d+)/g
+
+const parseCommandAccess = (value: string | undefined) => {
+  if (value === undefined || value.length === 0) {
+    return Effect.succeed(undefined)
+  }
+
+  switch (value) {
+    case 'read':
+    case 'write':
+    case 'destructive':
+      return Effect.succeed(value)
+    default:
+      return Effect.fail(
+        new SkillsetError({
+          cause: 'frontmatter_invalid',
+          message: 'Command access must be read, write, or destructive'
+        })
+      )
+  }
+}
+
+const parseBooleanField = (field: string, value: string | undefined) => {
+  if (value === undefined || value.length === 0) {
+    return Effect.succeed(undefined)
+  }
+
+  switch (value) {
+    case 'true':
+      return Effect.succeed(true)
+    case 'false':
+      return Effect.succeed(false)
+    default:
+      return Effect.fail(
+        new SkillsetError({
+          cause: 'frontmatter_invalid',
+          message: `${field} must be true or false`
+        })
+      )
+  }
+}
+
+const parseArgumentToken = (token: string) => {
+  const trimmed = token.trim()
+
+  if (trimmed.length === 0) {
+    return undefined
+  }
+
+  const required = !trimmed.endsWith('?')
+  const name = required ? trimmed : trimmed.slice(0, -1)
+
+  return name.length === 0 ? undefined : { name, required }
+}
+
+const parseCommandArgumentsField = (value: string | undefined): ReadonlyArray<CommandArgument> => {
+  if (value === undefined || value.length === 0) {
+    return []
+  }
+
+  return value.split(',').flatMap(token => {
+    const argument = parseArgumentToken(token)
+
+    return argument === undefined ? [] : [argument]
+  })
+}
+
+export const commandHints = (template: string) => {
+  const numbered = Array.from(
+    template.matchAll(numberedPlaceholderPattern),
+    match => `$${match[1]}`
+  )
+  const unique = [...new Set(numbered)].sort((a, b) => Number(a.slice(1)) - Number(b.slice(1)))
+
+  return template.includes('$ARGUMENTS') ? [...unique, '$ARGUMENTS'] : unique
+}
+
+export const parseCommandMarkdown = (input: ParseCommandInput) =>
+  Effect.gen(function* () {
+    const name = yield* validateSkillsetName(input.name)
+    const document = yield* parseMarkdownDocument(input.markdown)
+    const description = document.data.description
+    const access = yield* parseCommandAccess(document.data.access)
+    const fileRefs = yield* parseBooleanField('fileRefs', document.data.fileRefs)
+    const commandArguments = parseCommandArgumentsField(document.data.arguments)
+
+    return {
+      name,
+      description: description === undefined || description.length === 0 ? undefined : description,
+      template: document.content,
+      hints: commandHints(document.content),
+      ...(commandArguments.length === 0 ? {} : { arguments: commandArguments }),
+      ...(access === undefined ? {} : { access }),
+      ...(fileRefs === undefined ? {} : { fileRefs }),
+      location: input.location,
+      source: input.source
+    }
+  })
+
+export const parseCommandArguments = (input: string) => {
+  const result: string[] = []
+  let current = ''
+  let quote: 'single' | 'double' | undefined
+
+  for (const char of input.trim()) {
+    if (char === "'" && quote !== 'double') {
+      quote = quote === 'single' ? undefined : 'single'
+      continue
+    }
+
+    if (char === '"' && quote !== 'single') {
+      quote = quote === 'double' ? undefined : 'double'
+      continue
+    }
+
+    if (/\s/.test(char) && quote === undefined) {
+      if (current.length > 0) {
+        result.push(current)
+        current = ''
+      }
+      continue
+    }
+
+    current = `${current}${char}`
+  }
+
+  if (current.length > 0) {
+    result.push(current)
+  }
+
+  return result
+}
+
+export const renderCommand = (command: CommandInfo, argumentsText: string) => {
+  const args = parseCommandArguments(argumentsText)
+  const placeholders = Array.from(command.template.matchAll(numberedPlaceholderPattern), match =>
+    Number(match[1])
+  )
+  const lastPlaceholder = placeholders.reduce((max, value) => Math.max(max, value), 0)
+  const withNumbered = command.template.replace(numberedPlaceholderPattern, (_, index: string) => {
+    const position = Number(index)
+    const argIndex = position - 1
+
+    if (argIndex >= args.length) {
+      return ''
+    }
+
+    return position === lastPlaceholder ? args.slice(argIndex).join(' ') : (args[argIndex] ?? '')
+  })
+  const usesArguments = command.template.includes('$ARGUMENTS')
+  const rendered = withNumbered.replaceAll('$ARGUMENTS', argumentsText)
+
+  return placeholders.length === 0 && !usesArguments && argumentsText.trim().length > 0
+    ? `${rendered}\n\n${argumentsText}`.trim()
+    : rendered.trim()
+}

package/src/errors.ts

@@ -0,0 +1,16 @@
+import * as Schema from 'effect/Schema'
+
+export const SkillsetErrorCause = Schema.Literals([
+  'duplicate_entry',
+  'frontmatter_field_missing',
+  'frontmatter_invalid',
+  'frontmatter_missing',
+  'invalid_name',
+  'name_mismatch'
+])
+export type SkillsetErrorCause = typeof SkillsetErrorCause.Type
+
+export class SkillsetError extends Schema.TaggedErrorClass<SkillsetError>()('SkillsetError', {
+  cause: SkillsetErrorCause,
+  message: Schema.String
+}) {}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { SkillsetError, SkillsetErrorCause } from './errors.ts'
+export { isValidSkillsetName, validateDirectoryName, validateSkillsetName } from './name.ts'
+export { parseMarkdownDocument } from './markdown.ts'
+export type { MarkdownDocument } from './markdown.ts'
+export { SkillInfo, formatAvailableSkills, parseSkillMarkdown } from './skill.ts'
+export {
+  CommandArgument,
+  CommandAccess,
+  CommandInfo,
+  commandHints,
+  parseCommandArguments,
+  parseCommandMarkdown,
+  renderCommand
+} from './command.ts'
+export { SkillsetManifest, emptySkillsetManifest } from './manifest.ts'
+export { mergeSkillsets } from './merge.ts'
+export type { MergedSkillset, SkillsetSource } from './merge.ts'
+export type { ParseSkillInput } from './skill.ts'
+export type { ParseCommandInput } from './command.ts'

package/src/manifest.ts

@@ -0,0 +1,16 @@
+import * as Schema from 'effect/Schema'
+import { CommandInfo } from './command.ts'
+import { SkillInfo } from './skill.ts'
+
+export const SkillsetManifest = Schema.Struct({
+  version: Schema.Literal(1),
+  skills: Schema.Array(SkillInfo),
+  commands: Schema.Array(CommandInfo)
+})
+export type SkillsetManifest = typeof SkillsetManifest.Type
+
+export const emptySkillsetManifest: SkillsetManifest = {
+  version: 1,
+  skills: [],
+  commands: []
+}

package/src/markdown.ts

@@ -0,0 +1,74 @@
+import { Effect } from 'effect'
+import { SkillsetError } from './errors.ts'
+
+export type MarkdownDocument = {
+  readonly data: Readonly<Record<string, string>>
+  readonly content: string
+}
+
+const frontmatterStart = '---\n'
+
+const frontmatterEndIndex = (markdown: string) => markdown.indexOf('\n---', frontmatterStart.length)
+
+const parseFrontmatterLine = (line: string) => {
+  const separatorIndex = line.indexOf(':')
+
+  if (separatorIndex === -1) {
+    return undefined
+  }
+
+  const key = line.slice(0, separatorIndex).trim()
+  const value = line.slice(separatorIndex + 1).trim()
+
+  return key.length === 0 ? undefined : { key, value }
+}
+
+export const parseMarkdownDocument = (markdown: string) =>
+  Effect.gen(function* () {
+    if (!markdown.startsWith(frontmatterStart)) {
+      return yield* Effect.fail(
+        new SkillsetError({
+          cause: 'frontmatter_missing',
+          message: 'Markdown must start with YAML frontmatter'
+        })
+      )
+    }
+
+    const endIndex = frontmatterEndIndex(markdown)
+
+    if (endIndex === -1) {
+      return yield* Effect.fail(
+        new SkillsetError({
+          cause: 'frontmatter_invalid',
+          message: 'Markdown frontmatter is missing closing delimiter'
+        })
+      )
+    }
+
+    const entries = markdown
+      .slice(frontmatterStart.length, endIndex)
+      .split('\n')
+      .filter(line => line.trim().length > 0)
+      .map(parseFrontmatterLine)
+
+    if (entries.some(entry => entry === undefined)) {
+      return yield* Effect.fail(
+        new SkillsetError({
+          cause: 'frontmatter_invalid',
+          message: 'Markdown frontmatter only supports simple key: value fields'
+        })
+      )
+    }
+
+    const data = Object.fromEntries(
+      entries.flatMap(entry => (entry === undefined ? [] : [[entry.key, entry.value]]))
+    )
+    const contentStart = markdown.startsWith('\n', endIndex + frontmatterStart.length)
+      ? endIndex + frontmatterStart.length + 1
+      : endIndex + frontmatterStart.length
+
+    return {
+      data,
+      content: markdown.slice(contentStart).trim()
+    }
+  })

package/src/merge.ts

@@ -0,0 +1,61 @@
+import { Effect } from 'effect'
+import { SkillsetError } from './errors.ts'
+import type { CommandInfo } from './command.ts'
+import type { SkillInfo } from './skill.ts'
+import type { SkillsetManifest } from './manifest.ts'
+
+export type SkillsetSource = {
+  readonly id: string
+  readonly manifest: SkillsetManifest
+}
+
+export type MergedSkillset = {
+  readonly skills: ReadonlyArray<SkillInfo>
+  readonly commands: ReadonlyArray<CommandInfo>
+}
+
+const mergeByName = <Entry extends { readonly name: string }>(
+  entries: ReadonlyArray<ReadonlyArray<Entry>>
+) => {
+  const byName = new Map<string, Entry>()
+
+  const reversedEntries = [...entries].reverse()
+
+  reversedEntries.forEach(group => {
+    group.forEach(entry => byName.set(entry.name, entry))
+  })
+
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name))
+}
+
+const duplicateNames = <Entry extends { readonly name: string }>(entries: ReadonlyArray<Entry>) => {
+  const names = entries.map(entry => entry.name)
+
+  return [...new Set(names.filter((name, index) => names.indexOf(name) !== index))]
+}
+
+const rejectInternalDuplicates = (source: SkillsetSource) => {
+  const duplicates = [
+    ...duplicateNames(source.manifest.skills).map(name => `skill:${name}`),
+    ...duplicateNames(source.manifest.commands).map(name => `command:${name}`)
+  ]
+
+  return duplicates.length === 0
+    ? Effect.void
+    : Effect.fail(
+        new SkillsetError({
+          cause: 'duplicate_entry',
+          message: `Duplicate entries in source ${source.id}: ${duplicates.join(', ')}`
+        })
+      )
+}
+
+export const mergeSkillsets = (sources: ReadonlyArray<SkillsetSource>) =>
+  Effect.gen(function* () {
+    yield* Effect.forEach(sources, rejectInternalDuplicates, { discard: true })
+
+    return {
+      skills: mergeByName(sources.map(source => source.manifest.skills)),
+      commands: mergeByName(sources.map(source => source.manifest.commands))
+    }
+  })

package/src/name.ts

@@ -0,0 +1,28 @@
+import { Effect } from 'effect'
+import { SkillsetError } from './errors.ts'
+
+const skillsetNamePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const maxSkillsetNameLength = 64
+
+export const isValidSkillsetName = (name: string) =>
+  name.length > 0 && name.length <= maxSkillsetNameLength && skillsetNamePattern.test(name)
+
+export const validateSkillsetName = (name: string) =>
+  isValidSkillsetName(name)
+    ? Effect.succeed(name)
+    : Effect.fail(
+        new SkillsetError({
+          cause: 'invalid_name',
+          message: `Invalid skillset entry name: ${name}`
+        })
+      )
+
+export const validateDirectoryName = (expected: string, actual: string) =>
+  expected === actual
+    ? Effect.succeed(expected)
+    : Effect.fail(
+        new SkillsetError({
+          cause: 'name_mismatch',
+          message: `Skill name must match directory name: expected ${expected}, got ${actual}`
+        })
+      )

package/src/skill.ts

@@ -0,0 +1,72 @@
+import { Effect } from 'effect'
+import * as Schema from 'effect/Schema'
+import { SkillsetError } from './errors.ts'
+import { parseMarkdownDocument } from './markdown.ts'
+import { validateDirectoryName, validateSkillsetName } from './name.ts'
+
+export const SkillInfo = Schema.Struct({
+  name: Schema.String,
+  description: Schema.String,
+  location: Schema.String,
+  content: Schema.String,
+  source: Schema.optional(Schema.String)
+})
+export type SkillInfo = typeof SkillInfo.Type
+
+export type ParseSkillInput = {
+  readonly markdown: string
+  readonly location: string
+  readonly directoryName?: string
+  readonly source?: string
+}
+
+const requiredField = (data: Readonly<Record<string, string>>, field: string) => {
+  const value = data[field]
+
+  return value === undefined || value.length === 0
+    ? Effect.fail(
+        new SkillsetError({
+          cause: 'frontmatter_field_missing',
+          message: `Skill frontmatter requires ${field}`
+        })
+      )
+    : Effect.succeed(value)
+}
+
+export const parseSkillMarkdown = (input: ParseSkillInput) =>
+  Effect.gen(function* () {
+    const document = yield* parseMarkdownDocument(input.markdown)
+    const name = yield* requiredField(document.data, 'name').pipe(
+      Effect.flatMap(validateSkillsetName)
+    )
+    const description = yield* requiredField(document.data, 'description')
+
+    if (input.directoryName !== undefined) {
+      yield* validateDirectoryName(input.directoryName, name)
+    }
+
+    return {
+      name,
+      description,
+      location: input.location,
+      content: document.content,
+      source: input.source
+    }
+  })
+
+export const formatAvailableSkills = (skills: ReadonlyArray<SkillInfo>) =>
+  skills.length === 0
+    ? ''
+    : [
+        '<available_skills>',
+        ...skills
+          .slice()
+          .sort((a, b) => a.name.localeCompare(b.name))
+          .flatMap(skill => [
+            '  <skill>',
+            `    <name>${skill.name}</name>`,
+            `    <description>${skill.description}</description>`,
+            '  </skill>'
+          ]),
+        '</available_skills>'
+      ].join('\n')