@kuralle-agents/fs 0.11.0 → 0.12.0

package/dist/okf.js

@@ -0,0 +1,142 @@
+import { InMemoryFs } from './in-memory-fs.js';
+const RESERVED = new Set(['index.md', 'log.md']);
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)([\s\S]*)$/;
+const LINK_RE = /\[[^\]]*\]\(([^)]+)\)/g;
+/** Parse one OKF concept document. Throws only when `type` is missing (the sole hard rule, §9). */
+export function parseOkfConcept(content, id) {
+    const stripped = content.replace(/^/, '');
+    const match = stripped.match(FRONTMATTER_RE);
+    if (!match) {
+        throw new Error(`OKF: concept "${id}" is missing YAML frontmatter.`);
+    }
+    const fm = parseFlatYaml(match[1] ?? '');
+    const type = typeof fm.type === 'string' ? fm.type.trim() : '';
+    if (!type) {
+        throw new Error(`OKF: concept "${id}" frontmatter must define a non-empty "type" (spec §9).`);
+    }
+    const body = (match[2] ?? '').replace(/^\n/, '');
+    const links = extractBundleLinks(body);
+    const concept = { id, type, body, links };
+    const title = str(fm.title);
+    const description = str(fm.description);
+    const resource = str(fm.resource);
+    const timestamp = str(fm.timestamp);
+    if (title)
+        concept.title = title;
+    if (description)
+        concept.description = description;
+    if (resource)
+        concept.resource = resource;
+    if (Array.isArray(fm.tags))
+        concept.tags = fm.tags.map(String);
+    if (timestamp)
+        concept.timestamp = timestamp;
+    return concept;
+}
+/**
+ * List every concept in a bundle (skips reserved index.md/log.md). Permissive
+ * per §9: a concept whose frontmatter is unparseable or lacks `type` is skipped,
+ * not fatal — a partially-generated bundle stays consumable.
+ */
+export async function listOkfConcepts(fs, root = '/') {
+    const out = [];
+    const stack = [root === '' ? '/' : root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await fs.readdirWithFileTypes(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = fs.resolvePath(dir, entry.name);
+            if (entry.type === 'directory') {
+                stack.push(full);
+                continue;
+            }
+            if (!entry.name.endsWith('.md') || RESERVED.has(entry.name))
+                continue;
+            const id = full.replace(/^\//, '').replace(/\.md$/, '');
+            try {
+                out.push(parseOkfConcept(await fs.readFile(full), id));
+            }
+            catch {
+                // §9: tolerate non-conformant documents; skip rather than fail the bundle.
+            }
+        }
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Build an OKF bundle into an InMemoryFs from a `{ path: content }` map. */
+export function okfBundleToFs(files, mountRoot = '') {
+    const seeded = {};
+    for (const [path, content] of Object.entries(files)) {
+        const p = path.startsWith('/') ? path : `/${path}`;
+        seeded[`${mountRoot}${p}`] = content;
+    }
+    return new InMemoryFs(seeded);
+}
+function str(v) {
+    return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+}
+/** Bundle-relative links only (`/tables/x.md`) — the concept graph, ignoring external URLs. */
+function extractBundleLinks(body) {
+    const links = new Set();
+    let m;
+    LINK_RE.lastIndex = 0;
+    while ((m = LINK_RE.exec(body)) !== null) {
+        const target = (m[1] ?? '').trim();
+        if (target.startsWith('/') && target.endsWith('.md')) {
+            links.add(target.replace(/\.md$/, '').replace(/^\//, ''));
+        }
+    }
+    return [...links];
+}
+/** Minimal flat-YAML frontmatter parse (scalars + `tags: [a, b]` / `- item` lists). No node:*, workerd-clean. */
+function parseFlatYaml(yaml) {
+    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 km = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!km) {
+            i += 1;
+            continue;
+        }
+        const key = km[1];
+        const rest = (km[2] ?? '').trim();
+        if (rest.startsWith('[') && rest.endsWith(']')) {
+            const inner = rest.slice(1, -1).trim();
+            result[key] = inner === '' ? [] : inner.split(',').map((s) => scalar(s.trim()));
+            i += 1;
+            continue;
+        }
+        if (rest === '') {
+            i += 1;
+            const items = [];
+            while (i < lines.length && /^\s+-\s+/.test(lines[i])) {
+                items.push(scalar(lines[i].replace(/^\s+-\s+/, '')));
+                i += 1;
+            }
+            result[key] = items.length > 0 ? items : '';
+            continue;
+        }
+        result[key] = scalar(rest);
+        i += 1;
+    }
+    return result;
+}
+function scalar(v) {
+    const t = v.trim();
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}

package/dist/shell.d.ts

@@ -0,0 +1,2 @@
+export { bashShell, type BashLike } from './bash-shell.js';
+export { virtualShell, justBashFsToFileSystem } from './virtual-shell.js';

package/dist/shell.js

@@ -0,0 +1,8 @@
+// `@kuralle-agents/fs/shell` — the just-bash-backed virtual shell.
+//
+// Isolated from the root export because `just-bash`'s bundle pulls `turndown`,
+// which is not workerd-clean. Import this subpath on Node (and inside a CF
+// container); the root `@kuralle-agents/fs` stays Workers-clean. For a shell on
+// the Cloudflare edge, use `@kuralle-agents/fs/cloudflare` (a Sandbox DO wrapper).
+export { bashShell } from './bash-shell.js';
+export { virtualShell, justBashFsToFileSystem } from './virtual-shell.js';

package/dist/skill-frontmatter.d.ts

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,168 @@
+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;
+}

package/dist/sql/factory.d.ts

@@ -0,0 +1,33 @@
+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>>;
+    databaseSize: number;
+}
+/** Minimal structural shape of a D1Database. */
+export interface D1DatabaseLike {
+    prepare(query: string): {
+        bind(...values: SqlParam[]): {
+            all(): Promise<{
+                results: Record<string, SqlParam>[];
+            }>;
+            run(): Promise<unknown>;
+        };
+    };
+    batch(statements: unknown[]): Promise<unknown>;
+}
+export type SqlSource = SqlStorageLike | D1DatabaseLike | SqlBackend;
+export interface SqlFileSystemFactoryOptions {
+    namespace?: string;
+    blobs?: BlobStore;
+    inlineThreshold?: number;
+}
+/** Adapt any supported SQL source to the two-method SqlBackend. */
+export declare function toSqlBackend(src: SqlSource): SqlBackend;
+/**
+ * Persistent workspace filesystem over any SQL source. On Cloudflare pass a
+ * Durable Object's `ctx.storage.sql` or `env.DB` (D1); optionally `blobs` for
+ * large-file spillover to R2. Lazy-inits on first use.
+ */
+export declare function sqlFileSystem(source: SqlSource, options?: SqlFileSystemFactoryOptions): SqlFileSystem;

package/dist/sql/factory.js

@@ -0,0 +1,41 @@
+import { SqlFileSystem } from './sql-fs.js';
+function isSqlStorage(src) {
+    return typeof src === 'object' && src !== null && 'databaseSize' in src;
+}
+function isD1(src) {
+    return (typeof src === 'object' &&
+        src !== null &&
+        'prepare' in src &&
+        'batch' in src);
+}
+/** Adapt any supported SQL source to the two-method SqlBackend. */
+export function toSqlBackend(src) {
+    if (isSqlStorage(src)) {
+        return {
+            query: (sql, ...params) => [...src.exec(sql, ...params)],
+            run: (sql, ...params) => {
+                src.exec(sql, ...params);
+            },
+        };
+    }
+    if (isD1(src)) {
+        return {
+            query: async (sql, ...params) => {
+                const r = await src.prepare(sql).bind(...params).all();
+                return r.results;
+            },
+            run: async (sql, ...params) => {
+                await src.prepare(sql).bind(...params).run();
+            },
+        };
+    }
+    return src;
+}
+/**
+ * Persistent workspace filesystem over any SQL source. On Cloudflare pass a
+ * Durable Object's `ctx.storage.sql` or `env.DB` (D1); optionally `blobs` for
+ * large-file spillover to R2. Lazy-inits on first use.
+ */
+export function sqlFileSystem(source, options) {
+    return new SqlFileSystem({ backend: toSqlBackend(source), ...options });
+}

package/dist/sql/libsql-http.d.ts

@@ -0,0 +1,9 @@
+import type { SqlBackend } from './types.js';
+export interface LibsqlHttpOptions {
+    /** Turso database URL — `libsql://…` or `https://…` (both accepted). */
+    url: string;
+    authToken: string;
+    /** Injectable for tests; defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+export declare function libsqlHttpBackend(opts: LibsqlHttpOptions): SqlBackend;

package/dist/sql/libsql-http.js

@@ -0,0 +1,69 @@
+function toCell(v) {
+    if (v === null || v === undefined)
+        return { type: 'null' };
+    if (typeof v === 'boolean')
+        return { type: 'integer', value: v ? '1' : '0' };
+    if (typeof v === 'number') {
+        return Number.isInteger(v) ? { type: 'integer', value: String(v) } : { type: 'float', value: v };
+    }
+    return { type: 'text', value: v };
+}
+function fromCell(c) {
+    switch (c.type) {
+        case 'null':
+            return null;
+        case 'integer':
+            return Number(c.value);
+        case 'float':
+            return typeof c.value === 'number' ? c.value : Number(c.value);
+        case 'text':
+        case 'blob':
+            return String(c.value ?? c.base64 ?? '');
+        default:
+            return null;
+    }
+}
+export function libsqlHttpBackend(opts) {
+    const base = opts.url.replace(/^libsql:\/\//, 'https://').replace(/\/$/, '');
+    const doFetch = opts.fetch ?? fetch;
+    async function pipeline(sql, args) {
+        const res = await doFetch(`${base}/v2/pipeline`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${opts.authToken}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                requests: [
+                    { type: 'execute', stmt: { sql, args: args.map(toCell) } },
+                    { type: 'close' },
+                ],
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`libsql HTTP ${res.status}: ${await res.text()}`);
+        }
+        const body = (await res.json());
+        const first = body.results[0];
+        if (!first || first.type === 'error') {
+            throw new Error(`libsql: ${first?.error?.message ?? 'unknown error'}`);
+        }
+        const result = first.response?.result ?? { cols: [], rows: [] };
+        return { cols: result.cols.map((c) => c.name), rows: result.rows };
+    }
+    return {
+        query: async (sql, ...args) => {
+            const { cols, rows } = await pipeline(sql, args);
+            return rows.map((row) => {
+                const obj = {};
+                cols.forEach((name, i) => {
+                    obj[name] = fromCell(row[i] ?? { type: 'null' });
+                });
+                return obj;
+            });
+        },
+        run: async (sql, ...args) => {
+            await pipeline(sql, args);
+        },
+    };
+}

package/dist/sql/r2-blob.d.ts

@@ -0,0 +1,11 @@
+import type { BlobStore } from './types.js';
+export interface R2Bucketish {
+    get(key: string): Promise<{
+        arrayBuffer(): Promise<ArrayBuffer>;
+    } | null>;
+    put(key: string, data: ArrayBuffer | Uint8Array): Promise<unknown>;
+    delete(key: string): Promise<unknown>;
+}
+export declare function r2BlobStore(bucket: R2Bucketish, opts?: {
+    prefix?: string;
+}): BlobStore;

package/dist/sql/r2-blob.js

@@ -0,0 +1,18 @@
+export function r2BlobStore(bucket, opts) {
+    const prefix = opts?.prefix ?? '';
+    const k = (key) => `${prefix}${key}`;
+    return {
+        async get(key) {
+            const obj = await bucket.get(k(key));
+            if (!obj)
+                return null;
+            return new Uint8Array(await obj.arrayBuffer());
+        },
+        async put(key, data) {
+            await bucket.put(k(key), data);
+        },
+        async delete(key) {
+            await bucket.delete(k(key));
+        },
+    };
+}

package/dist/sql/sql-fs.d.ts

@@ -0,0 +1,50 @@
+import type { CpOptions, FileSystem, FileSystemDirent, FsStat, MkdirOptions, RmOptions } from '@kuralle-agents/core';
+import type { BlobStore, SqlBackend } from './types.js';
+export interface SqlFileSystemOptions {
+    backend: SqlBackend;
+    namespace?: string;
+    blobs?: BlobStore;
+    inlineThreshold?: number;
+}
+export declare class SqlFileSystem implements FileSystem {
+    private readonly backend;
+    private readonly namespace;
+    private readonly tableName;
+    private readonly indexName;
+    private readonly blobs;
+    private readonly threshold;
+    private initPromise;
+    constructor(opts: SqlFileSystemOptions);
+    init(): Promise<void>;
+    private ensureInit;
+    private doInit;
+    private missing;
+    private blobKey;
+    private getRow;
+    private readBytesFromRow;
+    private deleteBlobIfNeeded;
+    private insertDirectory;
+    private scaffoldForPath;
+    private locate;
+    private canonicalize;
+    readFile(path: string): Promise<string>;
+    readFileBytes(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string): Promise<void>;
+    writeFileBytes(path: string, content: Uint8Array): Promise<void>;
+    appendFile(path: string, content: string | Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<FileSystemDirent[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    private deleteDescendants;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    resolvePath(base: string, path: string): string;
+    glob(pattern: string): Promise<string[]>;
+}