@batonfx/skills 0.4.0 → 0.4.2

package/dist/instructions-files.d.ts

@@ -0,0 +1,14 @@
+import { Effect, FileSystem, Path, PlatformError } from "effect";
+/** @experimental Loaded instruction-file content. */
+export interface InstructionFile {
+    readonly path: string;
+    readonly content: string;
+}
+/** @experimental Instruction-file discovery options. */
+export interface LoadInstructionFilesOptions {
+    readonly filenames?: ReadonlyArray<string>;
+    readonly cwd?: string;
+    readonly globalFiles?: ReadonlyArray<string>;
+}
+/** @experimental Load AGENTS.md / CLAUDE.md instruction files. */
+export declare const loadInstructionFiles: (options?: LoadInstructionFilesOptions) => Effect.Effect<ReadonlyArray<InstructionFile>, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path>;

package/dist/instructions-files.js

@@ -0,0 +1,42 @@
+import { Effect, FileSystem, Path, PlatformError } from "effect";
+const DEFAULT_FILENAMES = ["AGENTS.md", "CLAUDE.md"];
+const readIfExists = (fs, file) => Effect.gen(function* () {
+    if (!(yield* fs.exists(file)))
+        return undefined;
+    const content = yield* fs.readFileString(file);
+    return { path: file, content };
+});
+const ancestors = (path, cwd) => {
+    const directories = [];
+    let cursor = path.resolve(cwd);
+    while (true) {
+        directories.push(cursor);
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    return directories.toReversed();
+};
+/** @experimental Load AGENTS.md / CLAUDE.md instruction files. */
+export const loadInstructionFiles = (options = {}) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const filenames = options.filenames ?? DEFAULT_FILENAMES;
+    const files = [];
+    for (const globalFile of options.globalFiles ?? []) {
+        const loaded = yield* readIfExists(fs, globalFile);
+        if (loaded !== undefined)
+            files.push(loaded);
+    }
+    for (const directory of ancestors(path, options.cwd ?? ".")) {
+        for (const filename of filenames) {
+            const loaded = yield* readIfExists(fs, path.join(directory, filename));
+            if (loaded !== undefined) {
+                files.push(loaded);
+                break;
+            }
+        }
+    }
+    return files;
+});

package/dist/s3-catalog.d.ts

@@ -0,0 +1,16 @@
+import { Crypto } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { SkillSource } from "@batonfx/core";
+import { type Limits } from "./hosted-catalog.js";
+/** @experimental Manifest-backed S3 catalog options. */
+export interface Options extends Limits {
+    readonly bucket: string;
+    readonly region: string;
+    readonly prefix?: string;
+    readonly manifestName?: string;
+    readonly source?: string;
+}
+/** @experimental Build a manifest-backed S3 catalog source. */
+export declare const make: (options: Options) => SkillSource.Source<HttpClient.HttpClient | Crypto.Crypto>;
+/** @experimental Build a manifest-backed S3 catalog layer. */
+export declare const layer: (options: Options) => import("effect/Layer").Layer<SkillSource.SkillSource, SkillSource.SkillSourceError, HttpClient.HttpClient | Crypto.Crypto>;

package/dist/s3-catalog.js

@@ -0,0 +1,33 @@
+import { Crypto, Effect } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { SkillSource } from "@batonfx/core";
+import { make as makeHostedCatalog, resolveRelative, validateSkillPath } from "./hosted-catalog.js";
+const segments = (value) => value
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(encodeURIComponent)
+    .join("/");
+/** @experimental Build a manifest-backed S3 catalog source. */
+export const make = (options) => {
+    const source = options.source ?? `s3://${options.bucket}/${options.prefix ?? ""}`;
+    if (!/^[a-z0-9](?:[a-z0-9-]{1,61})[a-z0-9]$/.test(options.bucket) ||
+        !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$/.test(options.region)) {
+        return Effect.fail(new SkillSource.SkillSourceError({ source, message: "Invalid S3 bucket or region for hosted skill catalog" }));
+    }
+    return Effect.gen(function* () {
+        if ((options.prefix?.length ?? 0) > 0)
+            yield* validateSkillPath(source, options.prefix ?? "");
+        yield* validateSkillPath(source, options.manifestName ?? "skills.json");
+        const prefix = segments(options.prefix ?? "");
+        const manifestName = segments(options.manifestName ?? "skills.json");
+        const manifestUrl = `https://${options.bucket}.s3.${options.region}.amazonaws.com/${prefix.length === 0 ? "" : `${prefix}/`}${manifestName}`;
+        return yield* makeHostedCatalog({
+            ...options,
+            source,
+            manifestUrl,
+            resolveSkillUrl: (skillPath) => resolveRelative(source, manifestUrl, skillPath),
+        });
+    });
+};
+/** @experimental Build a manifest-backed S3 catalog layer. */
+export const layer = (options) => SkillSource.layer([make(options)]);

package/dist/skill-document.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import { SkillSource } from "@batonfx/core";
+export interface ParsedDocument {
+    readonly frontmatter: SkillSource.Frontmatter;
+    readonly body: string;
+}
+export declare const splitDocument: (source: string, content: string) => Effect.Effect<readonly [string, string], SkillSource.SkillSourceError>;
+export declare const validateName: (source: string, name: string) => Effect.Effect<string, SkillSource.SkillSourceError>;
+export declare const parseFrontmatter: (source: string, block: string, directoryName: string) => Effect.Effect<SkillSource.Frontmatter, SkillSource.SkillSourceError>;
+export declare const parseDocument: (source: string, content: string, directoryName: string) => Effect.Effect<ParsedDocument, SkillSource.SkillSourceError>;

package/dist/skill-document.js

@@ -0,0 +1,144 @@
+import { Effect } from "effect";
+import { SkillSource } from "@batonfx/core";
+const sourceError = (source, message, cause) => new SkillSource.SkillSourceError({ source, message, ...(cause === undefined ? {} : { cause }) });
+const normalizeKey = (key) => key.replace(/[-_]/g, "").toLowerCase();
+const stripQuotes = (value) => {
+    const trimmed = value.trim();
+    return (trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+        ? trimmed.slice(1, -1)
+        : trimmed;
+};
+const parseInlineArray = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return [];
+    const inner = trimmed.slice(1, -1).trim();
+    return inner.length === 0 ? [] : inner.split(",").map((item) => stripQuotes(item).trim());
+};
+const parseBoolean = (value) => {
+    const lowered = value.trim().toLowerCase();
+    if (lowered === "true")
+        return true;
+    if (lowered === "false")
+        return false;
+    return undefined;
+};
+const setValue = (target, key, value) => {
+    switch (normalizeKey(key)) {
+        case "name":
+            if (typeof value === "string")
+                target.name = value;
+            break;
+        case "description":
+            if (typeof value === "string")
+                target.description = value;
+            break;
+        case "whentouse":
+            if (typeof value === "string")
+                target.whenToUse = value;
+            break;
+        case "allowedtools":
+            if (typeof value === "string")
+                target.allowedTools = value.split(/\s+/).filter((item) => item.length > 0);
+            else if (Array.isArray(value))
+                target.allowedTools = value;
+            break;
+        case "disablemodelinvocation":
+            if (typeof value === "boolean")
+                target.disableModelInvocation = value;
+            break;
+        case "userinvocable":
+            if (typeof value === "boolean")
+                target.userInvocable = value;
+            break;
+        case "contextfork":
+            if (typeof value === "boolean")
+                target.contextFork = value;
+            break;
+        case "agent":
+            if (typeof value === "string")
+                target.agent = value;
+            break;
+        case "model":
+            if (typeof value === "string")
+                target.model = value;
+            break;
+        case "paths":
+            if (Array.isArray(value))
+                target.paths = value;
+            break;
+    }
+};
+const parseHeader = (source, block) => Effect.sync(() => {
+    const parsed = {};
+    const lines = block.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index]?.trimEnd() ?? "";
+        if (line.trim().length === 0)
+            continue;
+        const separator = line.indexOf(":");
+        if (separator === -1)
+            continue;
+        const key = line.slice(0, separator).trim();
+        const raw = line.slice(separator + 1).trim();
+        if (raw.length === 0) {
+            const values = [];
+            while ((lines[index + 1]?.trimStart().startsWith("- ") ?? false) === true) {
+                index += 1;
+                values.push(stripQuotes((lines[index] ?? "").trimStart().slice(2)));
+            }
+            setValue(parsed, key, values);
+        }
+        else if (raw.startsWith("[") && raw.endsWith("]")) {
+            setValue(parsed, key, parseInlineArray(raw));
+        }
+        else {
+            setValue(parsed, key, parseBoolean(raw) ?? stripQuotes(raw));
+        }
+    }
+    return parsed;
+}).pipe(Effect.catchCause((cause) => Effect.fail(sourceError(source, "Invalid SKILL.md frontmatter", cause))));
+export const splitDocument = (source, content) => Effect.gen(function* () {
+    const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    if (lines[0] !== "---") {
+        return yield* Effect.fail(sourceError(source, "Invalid SKILL.md document: missing opening frontmatter fence"));
+    }
+    const close = lines.findIndex((line, index) => index > 0 && line === "---");
+    if (close === -1) {
+        return yield* Effect.fail(sourceError(source, "Invalid SKILL.md document: missing closing frontmatter fence"));
+    }
+    return [lines.slice(1, close).join("\n"), lines.slice(close + 1).join("\n")];
+});
+export const validateName = (source, name) => /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(name) && !name.includes("--")
+    ? Effect.succeed(name)
+    : Effect.fail(sourceError(source, "SKILL.md name must be 1-64 lowercase alphanumeric or single-hyphen-separated characters"));
+export const parseFrontmatter = (source, block, directoryName) => Effect.gen(function* () {
+    const parsed = yield* parseHeader(source, block);
+    if (parsed.name === undefined) {
+        return yield* Effect.fail(sourceError(source, "SKILL.md frontmatter requires name"));
+    }
+    yield* validateName(source, parsed.name);
+    if (parsed.name !== directoryName) {
+        return yield* Effect.fail(sourceError(source, `SKILL.md name must match directory ${directoryName}`));
+    }
+    if (parsed.description === undefined || parsed.description.length === 0 || parsed.description.length > 1_024) {
+        return yield* Effect.fail(sourceError(source, "SKILL.md description must contain 1-1024 characters"));
+    }
+    return {
+        name: parsed.name,
+        description: parsed.description,
+        ...(parsed.whenToUse === undefined ? {} : { whenToUse: parsed.whenToUse }),
+        ...(parsed.allowedTools === undefined ? {} : { allowedTools: parsed.allowedTools }),
+        ...(parsed.disableModelInvocation === undefined ? {} : { disableModelInvocation: parsed.disableModelInvocation }),
+        ...(parsed.userInvocable === undefined ? {} : { userInvocable: parsed.userInvocable }),
+        ...(parsed.contextFork === undefined ? {} : { contextFork: parsed.contextFork }),
+        ...(parsed.agent === undefined ? {} : { agent: parsed.agent }),
+        ...(parsed.model === undefined ? {} : { model: parsed.model }),
+        ...(parsed.paths === undefined ? {} : { paths: parsed.paths }),
+    };
+});
+export const parseDocument = (source, content, directoryName) => Effect.gen(function* () {
+    const [header, body] = yield* splitDocument(source, content);
+    return { frontmatter: yield* parseFrontmatter(source, header, directoryName), body };
+});

package/dist/skill-loader.d.ts

@@ -0,0 +1,13 @@
+import { FileSystem, Layer, Path } from "effect";
+import { SkillSource } from "@batonfx/core";
+/** @experimental Filesystem skill-loader options. */
+export interface LoadOptions {
+    readonly roots?: ReadonlyArray<string>;
+    readonly cwd?: string;
+    readonly descriptionCap?: number;
+    readonly frontmatterMaxBytes?: number;
+}
+/** @experimental Build a composable SkillSource from filesystem roots. */
+export declare const make: (options?: LoadOptions) => SkillSource.Source<FileSystem.FileSystem | Path.Path>;
+/** @experimental Build a SkillSource layer from filesystem roots. */
+export declare const layer: (options?: LoadOptions) => Layer.Layer<SkillSource.SkillSource, SkillSource.SkillSourceError, FileSystem.FileSystem | Path.Path>;

package/dist/skill-loader.js

@@ -0,0 +1,56 @@
+import { Effect, FileSystem, Layer, Path, PlatformError, Stream } from "effect";
+import { SkillSource } from "@batonfx/core";
+import { parseDocument, parseFrontmatter, splitDocument } from "./skill-document.js";
+const DEFAULT_ROOTS = [".agents/skills", ".claude/skills", ".pi/skills"];
+const decoder = new TextDecoder();
+const sourceError = (source, message, cause) => new SkillSource.SkillSourceError({ source, message, ...(cause === undefined ? {} : { cause }) });
+const mapPlatformError = (source, error) => sourceError(source, error.message, error);
+const readHeader = (fs, source, bytes) => fs.stream(source, { bytesToRead: bytes, chunkSize: bytes }).pipe(Stream.runFold(() => "", (content, chunk) => `${content}${decoder.decode(chunk)}`), Effect.mapError((error) => mapPlatformError(source, error)));
+const loadSkill = (fs, path, file, relativeFile, descriptionCap, frontmatterMaxBytes) => Effect.gen(function* () {
+    const header = yield* readHeader(fs, file, frontmatterMaxBytes);
+    const [headerBlock] = yield* splitDocument(file, header);
+    const directoryName = path.basename(path.dirname(relativeFile));
+    const frontmatter = yield* parseFrontmatter(file, headerBlock, directoryName);
+    return {
+        frontmatter,
+        listing: SkillSource.makeListing(frontmatter, descriptionCap),
+        body: fs.readFileString(file).pipe(Effect.mapError((error) => mapPlatformError(file, error)), Effect.flatMap((content) => parseDocument(file, content, directoryName).pipe(Effect.map((document) => document.body)))),
+        tools: [],
+    };
+});
+const discoverRoot = (fs, path, cwd, root, descriptionCap, frontmatterMaxBytes) => Effect.gen(function* () {
+    const rootPath = path.isAbsolute(root) ? path.normalize(root) : path.join(cwd, root);
+    const exists = yield* fs.exists(rootPath).pipe(Effect.mapError((error) => mapPlatformError(rootPath, error)));
+    if (!exists)
+        return [];
+    const entries = yield* fs
+        .readDirectory(rootPath, { recursive: true })
+        .pipe(Effect.mapError((error) => mapPlatformError(rootPath, error)));
+    const skills = [];
+    for (const skillFile of entries.filter((entry) => path.basename(entry) === "SKILL.md").toSorted()) {
+        skills.push(yield* loadSkill(fs, path, path.join(rootPath, skillFile), skillFile, descriptionCap, frontmatterMaxBytes));
+    }
+    return skills;
+});
+/** @experimental Build a composable SkillSource from filesystem roots. */
+export const make = (options = {}) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const cwd = options.cwd === undefined ? "." : path.resolve(options.cwd);
+    const roots = options.roots ?? DEFAULT_ROOTS;
+    const descriptionCap = options.descriptionCap ?? SkillSource.DESCRIPTION_CAP;
+    const frontmatterMaxBytes = options.frontmatterMaxBytes ?? 64 * 1024;
+    const byName = new Map();
+    for (const root of roots) {
+        for (const skill of yield* discoverRoot(fs, path, cwd, root, descriptionCap, frontmatterMaxBytes)) {
+            byName.set(skill.frontmatter.name, skill);
+        }
+    }
+    const skills = [...byName.values()];
+    return {
+        all: Effect.succeed(skills),
+        get: (name) => Effect.succeed(byName.get(name)),
+    };
+});
+/** @experimental Build a SkillSource layer from filesystem roots. */
+export const layer = (options = {}) => Layer.effect(SkillSource.SkillSource, make(options).pipe(Effect.map(SkillSource.SkillSource.of)));

package/package.json

@@ -1,20 +1,23 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@batonfx/skills",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "private": false,
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir dist --target bun --format esm",
+    "build": "rm -rf dist && bun tsc -p tsconfig.build.json",
     "lint": "bun --cwd ../.. oxlint packages/skills/src packages/skills/test",
     "test": "bun --cwd ../.. vitest run packages/skills/test --passWithNoTests",
     "typecheck": "bun tsc --noEmit"
   },
   "dependencies": {
-    "@batonfx/core": "0.4.0",
+    "@batonfx/core": "0.4.2",
     "effect": "4.0.0-beta.93"
   },
   "devDependencies": {
@@ -22,5 +25,27 @@
     "@types/bun": "1.3.13",
     "typescript": "5.8.2",
     "vitest": "4.0.16"
+  },
+  "description": "Filesystem and hosted skill sources for Baton agents",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22",
+    "bun": ">=1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/In-Time-Tec/batonfx.git",
+    "directory": "packages/skills"
+  },
+  "homepage": "https://github.com/In-Time-Tec/batonfx#readme",
+  "bugs": {
+    "url": "https://github.com/In-Time-Tec/batonfx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/.turbo/turbo-build.log

@@ -1,5 +0,0 @@
-$ bun build ./src/index.ts --outdir dist --target bun --format esm
-Bundled 194 modules in 587ms
-
-  index.js  1.24 MB  (entry point)
-

package/src/github-catalog.ts

@@ -1,80 +0,0 @@
-import { Crypto, Effect } from "effect"
-import { HttpClient, Url } from "effect/unstable/http"
-import { SkillSource } from "@batonfx/core"
-import { type Limits, make as makeHostedCatalog, validateSkillPath } from "./hosted-catalog"
-
-/** @experimental Manifest-backed GitHub catalog options. */
-export interface Options extends Limits {
-  readonly owner: string
-  readonly repo: string
-  readonly ref: string
-  readonly root?: string
-  readonly manifestName?: string
-  readonly apiBaseUrl?: string
-  readonly source?: string
-}
-
-const encodedPath = (value: string): string =>
-  value
-    .split("/")
-    .filter((segment) => segment.length > 0)
-    .map(encodeURIComponent)
-    .join("/")
-
-/** @experimental Build a manifest-backed immutable GitHub catalog source. */
-export const make = (options: Options): SkillSource.Source<HttpClient.HttpClient | Crypto.Crypto> => {
-  const source = options.source ?? `github:${options.owner}/${options.repo}@${options.ref}`
-  if (!/^[0-9a-fA-F]{40}$|^[0-9a-fA-F]{64}$/.test(options.ref)) {
-    return Effect.fail(
-      new SkillSource.SkillSourceError({ source, message: "GitHub skill catalog ref must be a commit id" }),
-    )
-  }
-  if (
-    !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(options.owner) ||
-    !/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,98}[A-Za-z0-9])?$/.test(options.repo)
-  ) {
-    return Effect.fail(new SkillSource.SkillSourceError({ source, message: "Invalid GitHub owner or repository" }))
-  }
-  return Effect.gen(function* () {
-    if ((options.root?.length ?? 0) > 0) yield* validateSkillPath(source, options.root ?? "")
-    yield* validateSkillPath(source, options.manifestName ?? "skills.json")
-    const apiBase = yield* Effect.fromResult(Url.fromString(options.apiBaseUrl ?? "https://api.github.com")).pipe(
-      Effect.mapError(
-        (cause) => new SkillSource.SkillSourceError({ source, message: "Invalid GitHub API base URL", cause }),
-      ),
-    )
-    if (
-      apiBase.protocol !== "https:" ||
-      apiBase.username.length > 0 ||
-      apiBase.password.length > 0 ||
-      apiBase.search.length > 0 ||
-      apiBase.hash.length > 0
-    ) {
-      return yield* Effect.fail(new SkillSource.SkillSourceError({ source, message: "Invalid GitHub API base URL" }))
-    }
-    const base = apiBase.toString().replace(/\/$/, "")
-    const root = encodedPath(options.root ?? "")
-    const manifestName = encodedPath(options.manifestName ?? "skills.json")
-    const repository = `${base}/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}/contents`
-    const rootUrl = `${repository}/${root.length === 0 ? "" : `${root}/`}`
-    const manifestUrl = `${rootUrl}${manifestName}?ref=${encodeURIComponent(options.ref)}`
-    const headers = {
-      accept: "application/vnd.github.raw+json",
-      "x-github-api-version": "2022-11-28",
-    }
-    return yield* makeHostedCatalog({
-      ...options,
-      source,
-      manifestUrl,
-      manifestHeaders: headers,
-      bodyHeaders: headers,
-      resolveSkillUrl: (skillPath) =>
-        validateSkillPath(source, skillPath).pipe(
-          Effect.map((safePath) => `${rootUrl}${encodedPath(safePath)}?ref=${encodeURIComponent(options.ref)}`),
-        ),
-    })
-  })
-}
-
-/** @experimental Build a manifest-backed immutable GitHub catalog layer. */
-export const layer = (options: Options) => SkillSource.layer([make(options)])