@kuralle-agents/fs 0.12.0 → 0.14.0

package/README.md

@@ -103,6 +103,13 @@ const agent = defineAgent({
 
 `defineSkill({ name, description, instructions, resources })` builds an inline skill without a filesystem.
 
+Pass ordered roots to layer shared and project skills. Later roots win when two `SKILL.md` files
+declare the same `name`, and the winning root owns both the body and its resources:
+
+```ts
+skills: fsSkillStore(fs, ['/skills/shared', '/skills/project'])
+```
+
 ## Persistent workspaces (`SqlFileSystem`, platform-chosen)
 
 `InMemoryFs` is ephemeral. For a workspace that survives restarts — so agent files, skills, and the durable tool journal agree across process boundaries — use `SqlFileSystem`, a drop-in `FileSystem` over any SQL handle (+ optional blob store for large files). Pick the backend your platform gives you:
@@ -188,15 +195,15 @@ fs and shell tools are **non-replayed** (`replay: false`): they always execute f
 ## Examples
 
 ```bash
-bun packages/kuralle-fs/examples/kb-agent.ts
-bun packages/kuralle-fs/examples/skills-on-fs.ts   # deterministic, no key
-KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/composite-workspace.ts
-KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/workspace-skills-shell.ts  # live: model uses bash + a fs skill
-KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/okf-knowledge-agent.ts     # live: agent navigates an OKF bundle
-KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/okf-benchmark.ts           # benchmark: progressive vs whole-dump
-KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/skill-latency-spike.ts     # benchmark: with vs without skills
-bun packages/kuralle-fs/examples/persistent-workspace.ts   # SqlFileSystem: file+skill survive a restart
-KURALLE_EXAMPLE_PROVIDER=openai bun packages/kuralle-fs/examples/persistent-workspace-live.ts  # live: model writes, fresh runtime reads back
+bun packages/fs/examples/kb-agent.ts
+bun packages/fs/examples/skills-on-fs.ts   # deterministic, no key
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/fs/examples/composite-workspace.ts
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/fs/examples/workspace-skills-shell.ts  # live: model uses bash + a fs skill
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/fs/examples/okf-knowledge-agent.ts     # live: agent navigates an OKF bundle
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/fs/examples/okf-benchmark.ts           # benchmark: progressive vs whole-dump
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/fs/examples/skill-latency-spike.ts     # benchmark: with vs without skills
+bun packages/fs/examples/persistent-workspace.ts   # SqlFileSystem: file+skill survive a restart
+KURALLE_EXAMPLE_PROVIDER=openai bun packages/fs/examples/persistent-workspace-live.ts  # live: model writes, fresh runtime reads back
 ```
 
 ## License

package/dist/in-memory-fs.d.ts

@@ -1,5 +1,4 @@
 import type { BufferEncoding, CpOptions, FileContent, FileSystem, FileSystemDirent, FsStat, InitialFiles, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from '@kuralle-agents/core';
-export type { FileContent, FsStat, FileSystem };
 export interface FsData {
     [path: string]: import('@kuralle-agents/core').FsEntry;
 }

package/dist/index.d.ts

@@ -4,9 +4,6 @@ export { CompositeFileSystem, type CompositeFileSystemConfig } from './composite
 export { normalizePath, validatePath, dirname, resolvePath, joinPath, resolveSymlinkTarget, createGlobMatcher, sortPaths, MAX_SYMLINK_DEPTH, DEFAULT_DIR_MODE, DEFAULT_FILE_MODE, SYMLINK_MODE, } from './path-utils.js';
 export { toBuffer, fromBuffer, getEncoding } from './encoding.js';
 export { createFsTool } from './tool.js';
-export { parseSkillFrontmatter, type ParsedSkill } from './skill-frontmatter.js';
-export { fsSkillStore } from './fs-skill-store.js';
-export { defineSkill } from './define-skill.js';
 export { parseOkfConcept, listOkfConcepts, okfBundleToFs, type OkfConcept, } from './okf.js';
 export { SqlFileSystem, type SqlFileSystemOptions } from './sql/sql-fs.js';
 export type { SqlBackend, BlobStore, SqlParam } from './sql/types.js';

package/dist/index.js

@@ -3,9 +3,6 @@ export { CompositeFileSystem } from './composite-fs.js';
 export { normalizePath, validatePath, dirname, resolvePath, joinPath, resolveSymlinkTarget, createGlobMatcher, sortPaths, MAX_SYMLINK_DEPTH, DEFAULT_DIR_MODE, DEFAULT_FILE_MODE, SYMLINK_MODE, } from './path-utils.js';
 export { toBuffer, fromBuffer, getEncoding } from './encoding.js';
 export { createFsTool } from './tool.js';
-export { parseSkillFrontmatter } from './skill-frontmatter.js';
-export { fsSkillStore } from './fs-skill-store.js';
-export { defineSkill } from './define-skill.js';
 export { parseOkfConcept, listOkfConcepts, okfBundleToFs, } from './okf.js';
 export { SqlFileSystem } from './sql/sql-fs.js';
 export { sqlFileSystem, toSqlBackend, } from './sql/factory.js';

package/dist/sql/factory.d.ts

@@ -2,7 +2,7 @@ import type { BlobStore, SqlBackend, SqlParam } from './types.js';
 import { SqlFileSystem } from './sql-fs.js';
 /** Minimal structural shape of a Cloudflare DO SqlStorage (no @cloudflare/workers-types dep). */
 export interface SqlStorageLike {
-    exec(query: string, ...bindings: SqlParam[]): Iterable<Record<string, SqlParam>>;
+    exec(query: string, ...bindings: SqlParam[]): Iterable<Record<string, SqlParam | ArrayBuffer>>;
     databaseSize: number;
 }
 /** Minimal structural shape of a D1Database. */

package/package.json

@@ -4,9 +4,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
-    "directory": "packages/kuralle-fs"
+    "directory": "packages/fs"
   },
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Portable filesystem primitive for Kuralle agents",
   "type": "module",
   "sideEffects": false,
@@ -31,16 +31,23 @@
     }
   },
   "dependencies": {
-    "just-bash": "^3.1.0",
-    "@kuralle-agents/core": "0.12.0"
+    "@kuralle-agents/core": "0.14.0"
   },
   "peerDependencies": {
+    "just-bash": "^3.1.0",
     "zod": "^4.0.0"
   },
+  "peerDependenciesMeta": {
+    "just-bash": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.12.7",
     "@types/node": "^22.5.0",
     "bun-types": "^1.3.0",
+    "dotenv": "^17.4.2",
+    "just-bash": "^3.1.0",
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0"
@@ -59,6 +66,7 @@
     "test": "bun test ./test && vitest run --config vitest.config.ts",
     "test:inmemoryfs": "bun test test/in-memory-fs.test.ts",
     "test:fs-tool": "bun test test/fs-tool.test.ts",
-    "test:fs-workers": "vitest run --config vitest.config.ts"
+    "test:fs-workers": "vitest run --config vitest.config.ts",
+    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json"
   }
 }

package/dist/define-skill.d.ts

@@ -1,7 +0,0 @@
-import type { SkillLike } from '@kuralle-agents/core';
-export declare function defineSkill(opts: {
-    name: string;
-    description: string;
-    instructions: string;
-    resources?: Record<string, string>;
-}): SkillLike;

package/dist/define-skill.js

@@ -1,8 +0,0 @@
-export function defineSkill(opts) {
-    return {
-        name: opts.name,
-        description: opts.description,
-        body: opts.instructions,
-        resources: opts.resources,
-    };
-}

package/dist/fs-skill-store.d.ts

@@ -1,4 +0,0 @@
-import type { FileSystem, SkillStoreLike } from '@kuralle-agents/core';
-export declare function fsSkillStore(fs: FileSystem, opts?: {
-    root?: string;
-}): SkillStoreLike;

package/dist/fs-skill-store.js

@@ -1,101 +0,0 @@
-import { parseSkillFrontmatter } from './skill-frontmatter.js';
-const DEFAULT_ROOT = '/skills';
-export function fsSkillStore(fs, opts) {
-    const root = opts?.root ?? DEFAULT_ROOT;
-    return {
-        async list() {
-            const metas = [];
-            let entries;
-            try {
-                entries = await fs.readdir(root);
-            }
-            catch {
-                return metas;
-            }
-            for (const entry of entries) {
-                const entryPath = fs.resolvePath(root, entry);
-                let stat;
-                try {
-                    stat = await fs.stat(entryPath);
-                }
-                catch {
-                    continue;
-                }
-                if (stat.type !== 'directory')
-                    continue;
-                const skillPath = fs.resolvePath(root, `${entry}/SKILL.md`);
-                if (!(await fs.exists(skillPath)))
-                    continue;
-                try {
-                    const content = await fs.readFile(skillPath);
-                    const parsed = parseSkillFrontmatter(content, { path: skillPath });
-                    metas.push({ name: parsed.name, description: parsed.description });
-                }
-                catch (err) {
-                    console.warn(`[skills] Skipping ${skillPath}: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-            return metas.sort((a, b) => a.name.localeCompare(b.name));
-        },
-        async loadBody(name) {
-            const folder = await findSkillFolder(fs, root, name);
-            if (!folder) {
-                throw new Error(`[skills] Skill "${name}" not found.`);
-            }
-            const skillPath = fs.resolvePath(root, `${folder}/SKILL.md`);
-            const content = await fs.readFile(skillPath);
-            const parsed = parseSkillFrontmatter(content, { path: skillPath });
-            return parsed.body;
-        },
-        async loadResource(name, path) {
-            const folder = await findSkillFolder(fs, root, name);
-            if (!folder) {
-                throw new Error(`[skills] Skill "${name}" not found.`);
-            }
-            const normalized = path.trim().replace(/^\.?\//, '');
-            if (normalized.includes('..') || normalized.startsWith('/')) {
-                throw new Error(`[skills] Invalid resource path "${path}".`);
-            }
-            const resourcePath = fs.resolvePath(root, `${folder}/${normalized}`);
-            if (!(await fs.exists(resourcePath))) {
-                const err = new Error(`ENOENT: [skills] Resource "${normalized}" not found for skill "${name}".`);
-                throw err;
-            }
-            return fs.readFile(resourcePath);
-        },
-    };
-}
-async function findSkillFolder(fs, root, name) {
-    let entries;
-    try {
-        entries = await fs.readdir(root);
-    }
-    catch {
-        return null;
-    }
-    for (const entry of entries) {
-        const entryPath = fs.resolvePath(root, entry);
-        let stat;
-        try {
-            stat = await fs.stat(entryPath);
-        }
-        catch {
-            continue;
-        }
-        if (stat.type !== 'directory')
-            continue;
-        const skillPath = fs.resolvePath(root, `${entry}/SKILL.md`);
-        if (!(await fs.exists(skillPath)))
-            continue;
-        try {
-            const content = await fs.readFile(skillPath);
-            const parsed = parseSkillFrontmatter(content, { path: skillPath });
-            if (parsed.name === name)
-                return entry;
-        }
-        catch {
-            continue;
-        }
-    }
-    return null;
-}

package/dist/interface.d.ts

@@ -1 +0,0 @@
-export type { FileSystem, FsStat, FileSystemDirent, FileSystemEntryType, BufferEncoding, FileContent, MkdirOptions, RmOptions, CpOptions, ReadFileOptions, WriteFileOptions, FileEntry, DirectoryEntry, SymlinkEntry, LazyFileEntry, FsEntry, FileInit, LazyFileProvider, InitialFiles, FsError, } from '@kuralle-agents/core';

package/dist/interface.js

@@ -1 +0,0 @@
-export {};

package/dist/skill-frontmatter.d.ts

@@ -1,12 +0,0 @@
-export interface ParsedSkill {
-    name: string;
-    description: string;
-    body: string;
-    license?: string;
-    compatibility?: string;
-    allowedTools?: string[];
-    metadata?: Record<string, string>;
-}
-export declare function parseSkillFrontmatter(content: string, ctx: {
-    path: string;
-}): ParsedSkill;

package/dist/skill-frontmatter.js

@@ -1,168 +0,0 @@
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)([\s\S]*)$/;
-const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-export function parseSkillFrontmatter(content, ctx) {
-    const stripped = content.replace(/^\uFEFF/, '');
-    const match = stripped.match(FRONTMATTER_RE);
-    if (!match) {
-        throw new Error(`[skills] Skill ${ctx.path} is missing YAML frontmatter.`);
-    }
-    const raw = parseFlatYaml(match[1] ?? '', ctx.path);
-    const name = requireField(raw, 'name', ctx.path);
-    const description = requireField(raw, 'description', ctx.path);
-    validateName(name, ctx.path);
-    validateDescription(description, ctx.path);
-    const compatibility = optionalString(raw.compatibility);
-    if (compatibility !== undefined && codePointLength(compatibility) > 500) {
-        throw new Error(`[skills] Skill ${ctx.path} field "compatibility" exceeds 500 characters.`);
-    }
-    let body = match[2] ?? '';
-    if (body.startsWith('\n')) {
-        body = body.slice(1);
-    }
-    const result = { name, description, body };
-    const license = optionalString(raw.license);
-    if (license !== undefined)
-        result.license = license;
-    if (compatibility !== undefined)
-        result.compatibility = compatibility;
-    const allowedTools = parseAllowedTools(raw['allowed-tools']);
-    if (allowedTools !== undefined)
-        result.allowedTools = allowedTools;
-    const metadata = parseMetadata(raw.metadata);
-    if (metadata !== undefined)
-        result.metadata = metadata;
-    return result;
-}
-function parseFlatYaml(yaml, path) {
-    const result = {};
-    const lines = yaml.split(/\r?\n/);
-    let i = 0;
-    while (i < lines.length) {
-        const line = lines[i];
-        if (line.trim() === '') {
-            i += 1;
-            continue;
-        }
-        const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-        if (!keyMatch) {
-            throw new Error(`[skills] Skill ${path} has invalid YAML frontmatter near line: ${line}`);
-        }
-        const key = keyMatch[1];
-        const rest = (keyMatch[2] ?? '').trim();
-        if (rest === '') {
-            i += 1;
-            if (i >= lines.length)
-                break;
-            const next = lines[i];
-            if (next.match(/^\s+-\s+/)) {
-                const items = [];
-                while (i < lines.length) {
-                    const listLine = lines[i];
-                    const itemMatch = listLine.match(/^\s+-\s+(.*)$/);
-                    if (!itemMatch)
-                        break;
-                    items.push(parseScalar(itemMatch[1] ?? ''));
-                    i += 1;
-                }
-                result[key] = items;
-                continue;
-            }
-            if (key === 'metadata') {
-                const meta = {};
-                while (i < lines.length) {
-                    const metaLine = lines[i];
-                    const metaMatch = metaLine.match(/^\s{2}([A-Za-z0-9_-]+):\s*(.*)$/);
-                    if (!metaMatch)
-                        break;
-                    meta[metaMatch[1]] = parseScalar((metaMatch[2] ?? '').trim());
-                    i += 1;
-                }
-                result[key] = meta;
-                continue;
-            }
-            result[key] = '';
-            continue;
-        }
-        if (rest.startsWith('[') && rest.endsWith(']')) {
-            const inner = rest.slice(1, -1).trim();
-            result[key] =
-                inner === ''
-                    ? []
-                    : inner.split(',').map((s) => parseScalar(s.trim()));
-            i += 1;
-            continue;
-        }
-        result[key] = parseScalar(rest);
-        i += 1;
-    }
-    return result;
-}
-function parseScalar(value) {
-    const trimmed = value.trim();
-    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
-        return trimmed.slice(1, -1);
-    }
-    return trimmed;
-}
-function requireField(raw, field, path) {
-    const value = raw[field];
-    if (typeof value !== 'string' || value.trim().length === 0) {
-        throw new Error(`[skills] Skill ${path} must define frontmatter ${field} as a non-empty string.`);
-    }
-    return value.trim();
-}
-function optionalString(value) {
-    if (typeof value !== 'string')
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-function validateName(name, path) {
-    if (name.length > 64) {
-        throw new Error(`[skills] Skill ${path} field "name" must be at most 64 characters.`);
-    }
-    if (!NAME_PATTERN.test(name)) {
-        throw new Error(`[skills] Skill ${path} field "name" "${name}" must match /^[a-z0-9]+(?:-[a-z0-9]+)*$/.`);
-    }
-}
-function validateDescription(description, path) {
-    if (codePointLength(description) > 1024) {
-        throw new Error(`[skills] Skill ${path} field "description" exceeds 1024 characters.`);
-    }
-}
-function codePointLength(value) {
-    return [...value].length;
-}
-function parseAllowedTools(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (Array.isArray(value)) {
-        const tools = value.map((v) => String(v).trim()).filter(Boolean);
-        return tools.length > 0 ? tools : undefined;
-    }
-    if (typeof value === 'string') {
-        const trimmed = value.trim();
-        if (!trimmed)
-            return undefined;
-        const tools = trimmed.includes(',')
-            ? trimmed.split(',').map((s) => s.trim()).filter(Boolean)
-            : trimmed.split(/\s+/).filter(Boolean);
-        return tools.length > 0 ? tools : undefined;
-    }
-    return undefined;
-}
-function parseMetadata(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (typeof value !== 'object' || Array.isArray(value))
-        return undefined;
-    const entries = Object.entries(value);
-    if (entries.length === 0)
-        return undefined;
-    const meta = {};
-    for (const [k, v] of entries) {
-        meta[k] = String(v);
-    }
-    return meta;
-}