@batonfx/skills 0.4.4 → 0.6.1

package/README.md

@@ -1,5 +1,55 @@
 # `@batonfx/skills`
 
-Filesystem and hosted skill sources for Baton agents.
+Focused composition guide for filesystem and hosted skill sources.
 
-See the [Baton documentation](https://github.com/In-Time-Tec/batonfx#readme) for installation, examples, and API guidance.
+## Install
+
+```sh
+bun add effect @effect/platform-bun @batonfx/core @batonfx/skills
+```
+
+## Imports
+
+```ts
+import { SkillSource } from "@batonfx/core"
+import { SkillLoader } from "@batonfx/skills"
+```
+
+## Layer graph
+
+```text
+BunServices.layer
+└─ provides FileSystem + Path
+   └─ SkillLoader.layer({ roots: [] })
+      └─ provides SkillSource.SkillSource
+```
+
+## Runnable program
+
+Checked source: [`../../examples/package-composition-guides/src/skills.ts`](../../examples/package-composition-guides/src/skills.ts)
+
+```ts
+import { Console, Effect, Layer } from "effect"
+import { BunServices } from "@effect/platform-bun"
+import { SkillSource } from "@batonfx/core"
+import { SkillLoader } from "@batonfx/skills"
+
+const skillLayer = SkillLoader.layer({ roots: [] }).pipe(Layer.provide(BunServices.layer))
+
+const program = SkillSource.SkillSource.use((source) =>
+  source.all.pipe(Effect.flatMap((skills) => Console.log(`discovered ${skills.length} skills`))),
+).pipe(Effect.provide(skillLayer))
+
+await Effect.runPromise(program)
+```
+
+Run `bun examples/package-composition-guides/src/skills.ts`.
+
+## Errors, requirements, and resources
+
+`BunServices.layer` provides the `FileSystem` and `Path` requirements used by `SkillLoader.layer`; the composed program has `R = never`, succeeds with `void`, and retains schema-backed `SkillSourceError` for filesystem, parsing, path, and validation failures. The layer owns platform services; this empty-root run performs no concurrent work and uses no timers, detached fibers, or unbounded buffers.
+
+## More
+
+- Current behavior: [Instructions and skills](../../docs/features/instructions-and-skills.md)
+- Deeper example: [capstone local assistant](../../examples/capstone-local-assistant/)

package/dist/github-catalog.d.ts

@@ -10,7 +10,6 @@ export interface Options extends Limits {
     readonly root?: string;
     readonly manifestName?: string;
     readonly apiBaseUrl?: string;
-    readonly source?: string;
 }
 /** @experimental Build a manifest-backed immutable GitHub catalog source. */
 export declare const make: (options: Options) => SkillSource.Source<HttpClient.HttpClient | Crypto.Crypto>;

package/dist/github-catalog.js

@@ -9,19 +9,23 @@ const encodedPath = (value) => value
     .join("/");
 /** @experimental Build a manifest-backed immutable GitHub catalog source. */
 export const make = (options) => {
-    const source = options.source ?? `github:${options.owner}/${options.repo}@${options.ref}`;
+    const validationSource = "github-skill-catalog";
     if (!/^[0-9a-fA-F]{40}$|^[0-9a-fA-F]{64}$/.test(options.ref)) {
-        return Effect.fail(SkillSource.SkillSourceError.make({ source, message: "GitHub skill catalog ref must be a commit id" }));
+        return Effect.fail(SkillSource.SkillSourceError.make({
+            source: validationSource,
+            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(SkillSource.SkillSourceError.make({ source, message: "Invalid GitHub owner or repository" }));
+        return Effect.fail(SkillSource.SkillSourceError.make({ source: validationSource, message: "Invalid GitHub owner or repository" }));
     }
+    const source = `github:${options.owner}/${options.repo}@${options.ref}`;
     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) => SkillSource.SkillSourceError.make({ source, message: "Invalid GitHub API base URL", cause })));
+        const apiBase = yield* Effect.fromResult(Url.fromString(options.apiBaseUrl ?? "https://api.github.com")).pipe(Effect.mapError(() => SkillSource.SkillSourceError.make({ source, message: "Invalid GitHub API base URL" })));
         if (apiBase.protocol !== "https:" ||
             apiBase.username.length > 0 ||
             apiBase.password.length > 0 ||
@@ -40,7 +44,7 @@ export const make = (options) => {
             "x-github-api-version": "2022-11-28",
         };
         return yield* makeHostedCatalog({
-            ...options,
+            limits: options,
             source,
             manifestUrl,
             manifestHeaders: headers,

package/dist/hosted-catalog.d.ts

@@ -1,43 +1,6 @@
-import { Crypto, Effect, Layer, Schema } from "effect";
+import { Crypto, Effect } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { SkillSource } from "@batonfx/core";
-/** @experimental Baton hosted skill manifest entry. */
-export declare const ManifestSkill: Schema.Struct<{
-    readonly name: Schema.String;
-    readonly description: Schema.String;
-    readonly skillPath: Schema.String;
-    readonly sha256: Schema.String;
-    readonly whenToUse: Schema.optionalKey<Schema.String>;
-    readonly allowedTools: Schema.optionalKey<Schema.$Array<Schema.String>>;
-    readonly disableModelInvocation: Schema.optionalKey<Schema.Boolean>;
-    readonly userInvocable: Schema.optionalKey<Schema.Boolean>;
-    readonly contextFork: Schema.optionalKey<Schema.Boolean>;
-    readonly agent: Schema.optionalKey<Schema.String>;
-    readonly model: Schema.optionalKey<Schema.String>;
-    readonly paths: Schema.optionalKey<Schema.$Array<Schema.String>>;
-}>;
-/** @experimental */
-export type ManifestSkill = typeof ManifestSkill.Type;
-/** @experimental Baton hosted skill manifest. */
-export declare const Manifest: Schema.Struct<{
-    readonly version: Schema.Literal<1>;
-    readonly skills: Schema.$Array<Schema.Struct<{
-        readonly name: Schema.String;
-        readonly description: Schema.String;
-        readonly skillPath: Schema.String;
-        readonly sha256: Schema.String;
-        readonly whenToUse: Schema.optionalKey<Schema.String>;
-        readonly allowedTools: Schema.optionalKey<Schema.$Array<Schema.String>>;
-        readonly disableModelInvocation: Schema.optionalKey<Schema.Boolean>;
-        readonly userInvocable: Schema.optionalKey<Schema.Boolean>;
-        readonly contextFork: Schema.optionalKey<Schema.Boolean>;
-        readonly agent: Schema.optionalKey<Schema.String>;
-        readonly model: Schema.optionalKey<Schema.String>;
-        readonly paths: Schema.optionalKey<Schema.$Array<Schema.String>>;
-    }>>;
-}>;
-/** @experimental */
-export type Manifest = typeof Manifest.Type;
 /** @experimental Shared hosted-catalog limits and trusted tools. */
 export interface Limits {
     readonly manifestMaxBytes?: number;
@@ -46,8 +9,8 @@ export interface Limits {
     readonly descriptionCap?: number;
     readonly toolsBySkill?: Readonly<Record<string, ReadonlyArray<SkillSource.Skill["tools"][number]>>>;
 }
-/** @experimental Internal hosted-catalog construction options. */
-export interface MakeOptions extends Limits {
+interface MakeOptions {
+    readonly limits: Limits;
     readonly source: string;
     readonly manifestUrl: string;
     readonly resolveSkillUrl: (skillPath: string) => Effect.Effect<string, SkillSource.SkillSourceError>;
@@ -66,5 +29,4 @@ export declare const resolveRelative: {
 };
 /** @experimental Build a hosted manifest source over Effect HTTP and Crypto services. */
 export declare const make: (options: MakeOptions) => SkillSource.Source<HttpClient.HttpClient | Crypto.Crypto>;
-/** @experimental One-source hosted catalog layer. */
-export declare const layer: (options: MakeOptions) => Layer.Layer<SkillSource.SkillSource, SkillSource.SkillSourceError, HttpClient.HttpClient | Crypto.Crypto>;
+export {};

package/dist/hosted-catalog.js

@@ -1,9 +1,8 @@
-import { Crypto, Effect, Encoding, Function, Layer, Schema, Stream } from "effect";
+import { Crypto, Effect, Encoding, Function, Schema, Stream } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse, Url } from "effect/unstable/http";
 import { SkillSource } from "@batonfx/core";
 import { parseDocument, validateName } from "./skill-document.js";
-/** @experimental Baton hosted skill manifest entry. */
-export const ManifestSkill = Schema.Struct({
+const ManifestSkill = Schema.Struct({
     name: Schema.String,
     description: Schema.String,
     skillPath: Schema.String,
@@ -17,8 +16,7 @@ export const ManifestSkill = Schema.Struct({
     model: Schema.optionalKey(Schema.String),
     paths: Schema.optionalKey(Schema.Array(Schema.String)),
 });
-/** @experimental Baton hosted skill manifest. */
-export const Manifest = Schema.Struct({
+const Manifest = Schema.Struct({
     version: Schema.Literal(1),
     skills: Schema.Array(ManifestSkill),
 });
@@ -33,7 +31,7 @@ const request = (url, headers) => {
         value = HttpClientRequest.setHeader(value, name, header);
     return value;
 };
-const fetchBytes = (client, source, url, headers, maxBytes) => client.execute(request(url, headers)).pipe(Effect.flatMap(HttpClientResponse.filterStatusOk), Effect.mapError((error) => sourceError(source, "Hosted skill request failed", error)), Effect.flatMap((response) => response.stream.pipe(Stream.mapError((error) => sourceError(source, "Hosted skill request failed", error)), Stream.runFoldEffect(() => ({ size: 0, chunks: [] }), (state, chunk) => {
+const fetchBytes = (client, source, url, headers, maxBytes) => client.execute(request(url, headers)).pipe(Effect.flatMap(HttpClientResponse.filterStatusOk), Effect.mapError(() => sourceError(source, "Hosted skill request failed")), Effect.flatMap((response) => response.stream.pipe(Stream.mapError(() => sourceError(source, "Hosted skill request failed")), Stream.runFoldEffect(() => ({ size: 0, chunks: [] }), (state, chunk) => {
     const size = state.size + chunk.byteLength;
     if (size > maxBytes) {
         return Effect.fail(sourceError(source, `Hosted skill response exceeds ${maxBytes} bytes`));
@@ -77,16 +75,16 @@ export const validateSkillPath = Function.dual(2, (source, skillPath) => {
         !skillPath.includes("#") &&
         segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..")
         ? Effect.succeed(skillPath)
-        : Effect.fail(sourceError(source, `Unsafe hosted skill path: ${skillPath}`));
+        : Effect.fail(sourceError(source, "Unsafe hosted skill path"));
 });
 /** @experimental Resolve a same-origin path beneath a manifest directory. */
 export const resolveRelative = Function.dual(3, (source, manifestUrl, skillPath) => Effect.gen(function* () {
     yield* validateSkillPath(source, skillPath);
-    const manifest = yield* Effect.fromResult(Url.fromString(manifestUrl)).pipe(Effect.mapError((error) => sourceError(source, "Invalid manifest URL", error)));
-    const directory = yield* Effect.fromResult(Url.fromString(".", manifest)).pipe(Effect.mapError((error) => sourceError(source, "Invalid manifest directory URL", error)));
-    const resolved = yield* Effect.fromResult(Url.fromString(skillPath, directory)).pipe(Effect.mapError((error) => sourceError(source, "Invalid hosted skill URL", error)));
+    const manifest = yield* Effect.fromResult(Url.fromString(manifestUrl)).pipe(Effect.mapError(() => sourceError(source, "Invalid manifest URL")));
+    const directory = yield* Effect.fromResult(Url.fromString(".", manifest)).pipe(Effect.mapError(() => sourceError(source, "Invalid manifest directory URL")));
+    const resolved = yield* Effect.fromResult(Url.fromString(skillPath, directory)).pipe(Effect.mapError(() => sourceError(source, "Invalid hosted skill URL")));
     if (resolved.origin !== manifest.origin || !resolved.pathname.startsWith(directory.pathname)) {
-        return yield* sourceError(source, `Hosted skill path escapes manifest directory: ${skillPath}`);
+        return yield* sourceError(source, "Hosted skill path escapes manifest directory");
     }
     return resolved.toString();
 }));
@@ -94,10 +92,10 @@ export const resolveRelative = Function.dual(3, (source, manifestUrl, skillPath)
 export const make = (options) => Effect.gen(function* () {
     const client = yield* HttpClient.HttpClient;
     const crypto = yield* Crypto.Crypto;
-    const manifestMaxBytes = yield* safeInteger(options.source, "manifestMaxBytes", options.manifestMaxBytes ?? 1024 * 1024, 1);
-    const bodyMaxBytes = yield* safeInteger(options.source, "bodyMaxBytes", options.bodyMaxBytes ?? 1024 * 1024, 1);
-    const maxSkills = yield* safeInteger(options.source, "maxSkills", options.maxSkills ?? 1_000, 1);
-    const descriptionCap = yield* safeInteger(options.source, "descriptionCap", options.descriptionCap ?? SkillSource.DESCRIPTION_CAP, 0);
+    const manifestMaxBytes = yield* safeInteger(options.source, "manifestMaxBytes", options.limits.manifestMaxBytes ?? 1024 * 1024, 1);
+    const bodyMaxBytes = yield* safeInteger(options.source, "bodyMaxBytes", options.limits.bodyMaxBytes ?? 1024 * 1024, 1);
+    const maxSkills = yield* safeInteger(options.source, "maxSkills", options.limits.maxSkills ?? 1_000, 1);
+    const descriptionCap = yield* safeInteger(options.source, "descriptionCap", options.limits.descriptionCap ?? SkillSource.DESCRIPTION_CAP, 0);
     const manifestBytes = yield* fetchBytes(client, options.source, options.manifestUrl, options.manifestHeaders, manifestMaxBytes);
     const manifestText = yield* decodeText(options.source, manifestBytes);
     const manifest = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(Manifest))(manifestText).pipe(Effect.mapError((error) => sourceError(options.source, "Invalid hosted skill manifest", error)));
@@ -127,8 +125,8 @@ export const make = (options) => Effect.gen(function* () {
             : Effect.fail(sourceError(options.source, `SHA-256 mismatch for hosted skill ${entry.name}`))))), Effect.flatMap((content) => parseDocument(options.source, content, entry.name).pipe(Effect.flatMap((document) => sameFrontmatter(document.frontmatter, metadata)
             ? Effect.succeed(document.body)
             : Effect.fail(sourceError(options.source, `Frontmatter mismatch for hosted skill ${entry.name}`))))));
-        const tools = options.toolsBySkill !== undefined && Object.hasOwn(options.toolsBySkill, entry.name)
-            ? (options.toolsBySkill[entry.name] ?? [])
+        const tools = options.limits.toolsBySkill !== undefined && Object.hasOwn(options.limits.toolsBySkill, entry.name)
+            ? (options.limits.toolsBySkill[entry.name] ?? [])
             : [];
         byName.set(entry.name, {
             frontmatter: metadata,
@@ -143,5 +141,3 @@ export const make = (options) => Effect.gen(function* () {
         get: (name) => Effect.succeed(byName.get(name)),
     };
 });
-/** @experimental One-source hosted catalog layer. */
-export const layer = (options) => Layer.effect(SkillSource.SkillSource, make(options).pipe(Effect.map(SkillSource.SkillSource.of)));

package/dist/http-catalog.d.ts

@@ -5,7 +5,6 @@ import { type Limits } from "./hosted-catalog.js";
 /** @experimental Generic HTTP skill catalog options. */
 export interface Options extends Limits {
     readonly manifestUrl: string;
-    readonly source?: string;
 }
 /** @experimental Build a generic HTTP catalog source. */
 export declare const make: (options: Options) => SkillSource.Source<HttpClient.HttpClient | Crypto.Crypto>;

package/dist/http-catalog.js

@@ -2,14 +2,15 @@ import { Crypto, Effect } from "effect";
 import { HttpClient, Url } from "effect/unstable/http";
 import { SkillSource } from "@batonfx/core";
 import { make as makeHostedCatalog, resolveRelative } from "./hosted-catalog.js";
-const invalidUrl = (cause) => SkillSource.SkillSourceError.make({ source: "http-skill-catalog", message: "Invalid manifest URL", cause });
+const invalidUrl = () => SkillSource.SkillSourceError.make({ source: "http-skill-catalog", message: "Invalid manifest URL" });
 /** @experimental Build a generic HTTP catalog source. */
 export const make = (options) => Effect.gen(function* () {
     const parsed = yield* Effect.fromResult(Url.fromString(options.manifestUrl)).pipe(Effect.mapError(invalidUrl));
-    const source = options.source ?? `${parsed.origin}${parsed.pathname}`;
+    const source = `${parsed.origin}${parsed.pathname}`;
     return yield* makeHostedCatalog({
-        ...options,
+        limits: options,
         source,
+        manifestUrl: options.manifestUrl,
         resolveSkillUrl: (skillPath) => resolveRelative(source, options.manifestUrl, skillPath),
     });
 });

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export * as GitHubCatalog from "./github-catalog.js";
-export * as HostedCatalog from "./hosted-catalog.js";
 export * as HttpCatalog from "./http-catalog.js";
 export * as InstructionFiles from "./instructions-files.js";
 export * as S3Catalog from "./s3-catalog.js";

package/dist/index.js

@@ -1,5 +1,4 @@
 export * as GitHubCatalog from "./github-catalog.js";
-export * as HostedCatalog from "./hosted-catalog.js";
 export * as HttpCatalog from "./http-catalog.js";
 export * as InstructionFiles from "./instructions-files.js";
 export * as S3Catalog from "./s3-catalog.js";

package/dist/s3-catalog.d.ts

@@ -8,7 +8,6 @@ export interface Options extends Limits {
     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>;

package/dist/s3-catalog.js

@@ -9,20 +9,24 @@ const segments = (value) => value
     .join("/");
 /** @experimental Build a manifest-backed S3 catalog source. */
 export const make = (options) => {
-    const source = options.source ?? `s3://${options.bucket}/${options.prefix ?? ""}`;
+    const validationSource = "s3-skill-catalog";
     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(SkillSource.SkillSourceError.make({ source, message: "Invalid S3 bucket or region for hosted skill catalog" }));
+        return Effect.fail(SkillSource.SkillSourceError.make({
+            source: validationSource,
+            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(validationSource, options.prefix ?? "");
+        const source = `s3://${options.bucket}/${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,
+            limits: options,
             source,
             manifestUrl,
             resolveSkillUrl: (skillPath) => resolveRelative(source, manifestUrl, skillPath),

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@batonfx/skills",
-  "version": "0.4.4",
+  "version": "0.6.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -17,11 +17,11 @@
     "typecheck": "bun tsc --noEmit"
   },
   "dependencies": {
-    "@batonfx/core": "0.4.4",
-    "effect": "4.0.0-beta.93"
+    "@batonfx/core": "0.6.1",
+    "effect": "4.0.0-beta.98"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-beta.93",
+    "@effect/vitest": "4.0.0-beta.98",
     "@types/bun": "1.3.13",
     "typescript": "7.0.2",
     "vitest": "4.0.16"