veryfront 0.1.934 → 0.1.936

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "veryfront",
-    "version": "0.1.934",
+    "version": "0.1.936",
     "license": "Apache-2.0",
     "nodeModulesDir": "auto",
     "minimumDependencyAge": {

package/esm/src/knowledge/index.d.ts

@@ -14,6 +14,7 @@
  */
 import "../../_dnt.polyfills.js";
 import type { RagSearchOptions, RagSearchResult, RagStoreBackend } from "../embedding/index.js";
+import type { Tool } from "../tool/types.js";
 /** Configuration for project knowledge indexing and retrieval. */
 export interface ProjectKnowledgeConfig {
     /**
@@ -54,6 +55,49 @@ export interface ProjectKnowledgeResult {
     matches: RagSearchResult[];
     context: string;
 }
+export interface ProjectKnowledgeLookupInput {
+    project_reference?: string;
+    query?: string;
+    cursor?: string;
+    lookup_target?: unknown;
+    limit?: number;
+    shard_count?: number;
+    shard_index?: number;
+}
+export interface ProjectKnowledgeLookupFrontmatterField {
+    key: string;
+    value: string;
+}
+export interface ProjectKnowledgeLookupItem {
+    path: string;
+    matched_fields: string[];
+    frontmatter: ProjectKnowledgeLookupFrontmatterField[];
+}
+export interface ProjectKnowledgeLookupPageInfo {
+    self: string | null;
+    first: string | null;
+    next: string | null;
+    prev: string | null;
+}
+export interface ProjectKnowledgeLookupShard {
+    shard_index: number;
+    shard_count: number;
+    total_items: number;
+}
+export interface ProjectKnowledgeLookupOutput {
+    query: string;
+    mode: "search" | "browse";
+    data: ProjectKnowledgeLookupItem[];
+    page_info: ProjectKnowledgeLookupPageInfo;
+    returned: number;
+    total_matches: number;
+    shard: ProjectKnowledgeLookupShard;
+}
+export interface CreateSearchKnowledgeToolOptions extends ProjectKnowledgeConfig {
+    id?: string;
+    description?: string;
+}
+export type SearchKnowledgeTool = Tool<ProjectKnowledgeLookupInput, ProjectKnowledgeLookupOutput>;
 /** Helper for indexing and retrieving project knowledge. */
 export interface ProjectKnowledge {
     /**
@@ -63,6 +107,12 @@ export interface ProjectKnowledge {
      * ingestion, or another controlled lifecycle step.
      */
     index(): Promise<void>;
+    /**
+     * Search the local OKF knowledge manifest using the same compact
+     * frontmatter-only response shape as Veryfront Cloud's `search_knowledge`
+     * tool. This does not build or query the embedding index.
+     */
+    lookup(input: ProjectKnowledgeLookupInput): Promise<ProjectKnowledgeLookupOutput>;
     retrieve(query: string, options?: ProjectKnowledgeRetrieveOptions): Promise<ProjectKnowledgeResult>;
     search(query: string, options?: RagSearchOptions): Promise<RagSearchResult[]>;
 }
@@ -70,6 +120,13 @@ export interface ProjectKnowledge {
 export declare function normalizeKnowledgeQuery(query: string, maxChars?: number): string;
 /** Format search results into a deterministic prompt context block. */
 export declare function formatKnowledgeContext(results: RagSearchResult[]): string;
+/**
+ * Search the local OKF knowledge manifest with the same input/output shape as
+ * Veryfront Cloud's `search_knowledge` MCP tool.
+ */
+export declare function searchProjectKnowledge(input: ProjectKnowledgeLookupInput, config?: ProjectKnowledgeConfig): Promise<ProjectKnowledgeLookupOutput>;
+/** Create a local tool with the same id and response shape as hosted `search_knowledge`. */
+export declare function createSearchKnowledgeTool(options?: CreateSearchKnowledgeToolOptions): SearchKnowledgeTool;
 /** Create a project knowledge helper backed by the configured RAG store. */
 export declare function projectKnowledge(config?: ProjectKnowledgeConfig): ProjectKnowledge;
 //# sourceMappingURL=index.d.ts.map

package/esm/src/knowledge/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/knowledge/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,yBAAyB,CAAC;AAIjC,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EAEf,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAQ/B,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wDAAwD;AACxD,MAAM,WAAW,+BAAgC,SAAQ,gBAAgB;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC/E;AAOD,oDAAoD;AACpD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAgC,GACzC,MAAM,CAER;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAIzE;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,sBAA2B,GAAG,gBAAgB,CAmDtF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/knowledge/index.ts"],"names":[],"mappings":"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"}

package/esm/src/knowledge/index.js

@@ -14,16 +14,395 @@
  */
 import "../../_dnt.polyfills.js";
 import { ragStore } from "../embedding/index.js";
-import { isAbsolute, join } from "../platform/compat/path/index.js";
+import { exists, readDir, readTextFile } from "../platform/compat/index.js";
+import { extract } from "../platform/compat/std/front-matter-yaml.js";
+import { isAbsolute, join, relative } from "../platform/compat/path/index.js";
+import { tool } from "../tool/factory.js";
 const DEFAULT_CONTENT_DIR = "knowledge";
 const DEFAULT_STORAGE_PATH = "data/knowledge-index.json";
 const DEFAULT_TOP_K = 3;
 const DEFAULT_QUERY_MAX_CHARS = 500;
+const DEFAULT_LOOKUP_LIMIT = 8;
+const MAX_LOOKUP_LIMIT = 12;
+const MAX_FRONTMATTER_FIELDS = 6;
+const MAX_FRONTMATTER_VALUE_LENGTH = 240;
+const KNOWLEDGE_LOOKUP_CURSOR_VERSION = 1;
+const FRONTMATTER_FIELD_PRIORITY = [
+    "title",
+    "name",
+    "description",
+    "summary",
+    "source",
+    "source_type",
+    "added",
+];
+const SEARCH_KNOWLEDGE_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_reference: {
+            type: "string",
+            description: "Project reference accepted for hosted/local parity.",
+        },
+        query: {
+            type: "string",
+            description: "Knowledge query to match against OKF frontmatter.",
+        },
+        cursor: {
+            type: "string",
+            description: "Cursor from a previous search_knowledge response.",
+        },
+        lookup_target: {
+            type: "object",
+            additionalProperties: true,
+            description: "Hosted lookup target accepted for API parity and ignored locally.",
+        },
+        limit: {
+            type: "integer",
+            description: "Maximum number of manifest entries to return.",
+        },
+        shard_count: {
+            type: "integer",
+            description: "Optional shard count for splitting large manifests.",
+        },
+        shard_index: {
+            type: "integer",
+            description: "Zero-based shard index.",
+        },
+    },
+    additionalProperties: false,
+};
 function resolveProjectPath(projectDir, path) {
     if (!projectDir || isAbsolute(path))
         return path;
     return join(projectDir, path);
 }
+function toPosixPath(path) {
+    return path.replace(/\\/g, "/");
+}
+function stripTrailingSlash(path) {
+    return toPosixPath(path).replace(/\/+$/, "");
+}
+function buildManifestPath(config, absolutePath) {
+    const contentDir = config.contentDir ?? DEFAULT_CONTENT_DIR;
+    const contentDirPath = resolveProjectPath(config.projectDir, contentDir);
+    const relativeToContent = toPosixPath(relative(contentDirPath, absolutePath));
+    if (!isAbsolute(contentDir)) {
+        const normalizedContentDir = stripTrailingSlash(contentDir).replace(/^\.\//, "");
+        return `${normalizedContentDir}/${relativeToContent}`;
+    }
+    if (config.projectDir) {
+        return toPosixPath(relative(config.projectDir, absolutePath));
+    }
+    return relativeToContent;
+}
+async function collectMarkdownFiles(dir) {
+    if (!(await exists(dir)))
+        return [];
+    const files = [];
+    for await (const entry of readDir(dir)) {
+        const entryPath = join(dir, entry.name);
+        if (entry.isDirectory) {
+            files.push(...await collectMarkdownFiles(entryPath));
+            continue;
+        }
+        if (entry.isFile && entry.name.endsWith(".md")) {
+            files.push(entryPath);
+        }
+    }
+    return files;
+}
+function normalizeText(value) {
+    return value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+function tokenize(value) {
+    return [
+        ...new Set(normalizeText(value)
+            .split(/\s+/)
+            .filter((token) => token.length >= 2)),
+    ];
+}
+function hashPath(value) {
+    let hash = 5381;
+    for (const char of value) {
+        hash = ((hash * 33) ^ char.charCodeAt(0)) >>> 0;
+    }
+    return hash;
+}
+function collapseFrontmatterValue(value) {
+    if (value == null)
+        return null;
+    let stringValue = "";
+    if (typeof value === "string") {
+        stringValue = value;
+    }
+    else if (typeof value === "number" || typeof value === "boolean") {
+        stringValue = String(value);
+    }
+    else if (value instanceof Date) {
+        if (Number.isNaN(value.getTime()))
+            return null;
+        const iso = value.toISOString();
+        stringValue = iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso;
+    }
+    else if (Array.isArray(value)) {
+        stringValue = value
+            .map((item) => collapseFrontmatterValue(item))
+            .filter((item) => typeof item === "string" && item.length > 0)
+            .join(", ");
+    }
+    else {
+        try {
+            stringValue = JSON.stringify(value);
+        }
+        catch {
+            stringValue = String(value);
+        }
+    }
+    const collapsed = stringValue.replace(/\s+/g, " ").trim();
+    return collapsed.length > 0 ? collapsed : null;
+}
+function truncateFrontmatterValue(value) {
+    if (value.length <= MAX_FRONTMATTER_VALUE_LENGTH)
+        return value;
+    return `${value.slice(0, MAX_FRONTMATTER_VALUE_LENGTH - 3)}...`;
+}
+function compareFrontmatterFields(left, right) {
+    const leftPriority = FRONTMATTER_FIELD_PRIORITY.indexOf(left.key);
+    const rightPriority = FRONTMATTER_FIELD_PRIORITY.indexOf(right.key);
+    if (leftPriority !== rightPriority) {
+        if (leftPriority === -1)
+            return 1;
+        if (rightPriority === -1)
+            return -1;
+        return leftPriority - rightPriority;
+    }
+    return left.key.localeCompare(right.key);
+}
+function collectFrontmatter(frontmatter) {
+    return Object.entries(frontmatter)
+        .map(([key, rawValue]) => {
+        const value = collapseFrontmatterValue(rawValue);
+        return value ? { key, value } : null;
+    })
+        .filter((entry) => entry !== null)
+        .sort(compareFrontmatterFields);
+}
+function sanitizeFrontmatter(frontmatter) {
+    const searchableFrontmatter = collectFrontmatter(frontmatter);
+    return {
+        frontmatter: searchableFrontmatter.slice(0, MAX_FRONTMATTER_FIELDS).map((field) => ({
+            key: field.key,
+            value: truncateFrontmatterValue(field.value),
+        })),
+        searchableFrontmatter,
+    };
+}
+function toSearchableEntry(entry) {
+    return {
+        ...entry,
+        normalizedPath: normalizeText(entry.path),
+        searchableFrontmatter: entry.searchableFrontmatter.map((field) => ({
+            ...field,
+            normalizedKey: normalizeText(field.key),
+            normalizedValue: normalizeText(field.value),
+        })),
+    };
+}
+function encodeCursor(state) {
+    const bytes = new TextEncoder().encode(JSON.stringify(state));
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeCursor(cursor) {
+    try {
+        const padded = cursor.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(cursor.length / 4) * 4, "=");
+        const binary = atob(padded);
+        const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        if (parsed.version !== KNOWLEDGE_LOOKUP_CURSOR_VERSION ||
+            typeof parsed.query !== "string" ||
+            typeof parsed.offset !== "number" ||
+            typeof parsed.limit !== "number" ||
+            typeof parsed.shardCount !== "number" ||
+            typeof parsed.shardIndex !== "number") {
+            throw new Error("Invalid cursor payload");
+        }
+        if (parsed.shardIndex < 0 || parsed.shardIndex >= parsed.shardCount) {
+            throw new Error("Cursor shard_index must be within shard_count");
+        }
+        return {
+            version: parsed.version,
+            query: parsed.query,
+            offset: parsed.offset,
+            limit: parsed.limit,
+            shardCount: parsed.shardCount,
+            shardIndex: parsed.shardIndex,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Could not decode cursor";
+        throw new Error(`Invalid knowledge lookup cursor: ${message}`);
+    }
+}
+function scoreEntry(entry, query, queryTokens) {
+    const matchedFields = new Set();
+    const normalizedQuery = normalizeText(query);
+    let score = 0;
+    if (normalizedQuery && entry.normalizedPath.includes(normalizedQuery)) {
+        score += 40;
+        matchedFields.add("path");
+    }
+    for (const field of entry.searchableFrontmatter) {
+        if (normalizedQuery && field.normalizedValue.includes(normalizedQuery)) {
+            score += 28;
+            matchedFields.add(field.key);
+        }
+        if (normalizedQuery && field.normalizedKey.includes(normalizedQuery)) {
+            score += 12;
+            matchedFields.add(field.key);
+        }
+    }
+    if (queryTokens.length > 1) {
+        for (const token of queryTokens) {
+            if (entry.normalizedPath.includes(token)) {
+                score += 10;
+                matchedFields.add("path");
+            }
+            for (const field of entry.searchableFrontmatter) {
+                if (field.normalizedValue.includes(token)) {
+                    score += 7;
+                    matchedFields.add(field.key);
+                }
+                if (field.normalizedKey.includes(token)) {
+                    score += 4;
+                    matchedFields.add(field.key);
+                }
+            }
+        }
+    }
+    return {
+        score,
+        matchedFields: [...matchedFields].sort((left, right) => left.localeCompare(right)),
+    };
+}
+async function getProjectKnowledgeManifest(config) {
+    const contentDir = resolveProjectPath(config.projectDir, config.contentDir ?? DEFAULT_CONTENT_DIR);
+    const files = (await collectMarkdownFiles(contentDir)).sort((left, right) => buildManifestPath(config, left).localeCompare(buildManifestPath(config, right)));
+    const manifest = [];
+    for (const file of files) {
+        let parsedFrontmatter = {};
+        try {
+            parsedFrontmatter = extract(await readTextFile(file)).attrs;
+        }
+        catch {
+            parsedFrontmatter = {};
+        }
+        manifest.push({
+            path: buildManifestPath(config, file),
+            ...sanitizeFrontmatter(parsedFrontmatter),
+        });
+    }
+    return manifest;
+}
+function lookupKnowledgeManifest(manifest, input) {
+    const cursorState = input.cursor ? decodeCursor(input.cursor) : null;
+    const providedQuery = input.query?.trim() ?? "";
+    const resolvedQuery = (cursorState?.query ?? providedQuery).trim();
+    if (!resolvedQuery) {
+        throw new Error("search_knowledge requires a non-empty query");
+    }
+    if (cursorState && providedQuery && providedQuery !== cursorState.query) {
+        throw new Error("search_knowledge cursor query mismatch");
+    }
+    const resolvedShardCount = cursorState?.shardCount ?? input.shard_count ?? 1;
+    const resolvedShardIndex = cursorState?.shardIndex ?? input.shard_index ?? 0;
+    if (resolvedShardCount < 1) {
+        throw new Error("search_knowledge shard_count must be at least 1");
+    }
+    if (resolvedShardIndex < 0 || resolvedShardIndex >= resolvedShardCount) {
+        throw new Error("search_knowledge shard_index must be within shard_count");
+    }
+    const resolvedLimit = Math.min(Math.max(cursorState?.limit ?? input.limit ?? DEFAULT_LOOKUP_LIMIT, 1), MAX_LOOKUP_LIMIT);
+    const resolvedOffset = Math.max(cursorState?.offset ?? 0, 0);
+    const queryTokens = tokenize(resolvedQuery);
+    const shardEntries = manifest
+        .filter((entry) => hashPath(entry.path) % resolvedShardCount === resolvedShardIndex)
+        .map(toSearchableEntry);
+    const scoredEntries = shardEntries
+        .map((entry) => ({
+        entry,
+        ...scoreEntry(entry, resolvedQuery, queryTokens),
+    }))
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return left.entry.path.localeCompare(right.entry.path);
+    });
+    const hasScoredMatches = scoredEntries.some((entry) => entry.score > 0);
+    const mode = hasScoredMatches ? "search" : "browse";
+    const orderedEntries = hasScoredMatches
+        ? scoredEntries.filter((entry) => entry.score > 0)
+        : scoredEntries;
+    const pageEntries = orderedEntries.slice(resolvedOffset, resolvedOffset + resolvedLimit);
+    const nextOffset = resolvedOffset + pageEntries.length;
+    const hasMore = nextOffset < orderedEntries.length;
+    const nextCursor = hasMore
+        ? encodeCursor({
+            version: KNOWLEDGE_LOOKUP_CURSOR_VERSION,
+            query: resolvedQuery,
+            offset: nextOffset,
+            limit: resolvedLimit,
+            shardCount: resolvedShardCount,
+            shardIndex: resolvedShardIndex,
+        })
+        : null;
+    return {
+        query: resolvedQuery,
+        mode,
+        data: pageEntries.map(({ entry, matchedFields }) => ({
+            path: entry.path,
+            matched_fields: matchedFields,
+            frontmatter: entry.frontmatter,
+        })),
+        page_info: {
+            self: input.cursor ?? null,
+            first: null,
+            next: nextCursor,
+            prev: null,
+        },
+        returned: pageEntries.length,
+        total_matches: orderedEntries.length,
+        shard: {
+            shard_index: resolvedShardIndex,
+            shard_count: resolvedShardCount,
+            total_items: shardEntries.length,
+        },
+    };
+}
+function coerceSearchKnowledgeInput(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("search_knowledge input must be an object");
+    }
+    const value = input;
+    return {
+        project_reference: typeof value.project_reference === "string"
+            ? value.project_reference
+            : undefined,
+        query: typeof value.query === "string" ? value.query : undefined,
+        cursor: typeof value.cursor === "string" ? value.cursor : undefined,
+        lookup_target: value.lookup_target,
+        limit: typeof value.limit === "number" ? value.limit : undefined,
+        shard_count: typeof value.shard_count === "number" ? value.shard_count : undefined,
+        shard_index: typeof value.shard_index === "number" ? value.shard_index : undefined,
+    };
+}
 /** Normalize a knowledge query before retrieval. */
 export function normalizeKnowledgeQuery(query, maxChars = DEFAULT_QUERY_MAX_CHARS) {
     return query.replace(/\s+/g, " ").trim().slice(0, maxChars);
@@ -34,6 +413,25 @@ export function formatKnowledgeContext(results) {
         .map((result) => `[${result.title}] (score: ${result.score.toFixed(2)})\n${result.text}`)
         .join("\n\n---\n\n");
 }
+/**
+ * Search the local OKF knowledge manifest with the same input/output shape as
+ * Veryfront Cloud's `search_knowledge` MCP tool.
+ */
+export async function searchProjectKnowledge(input, config = {}) {
+    const manifest = await getProjectKnowledgeManifest(config);
+    return lookupKnowledgeManifest(manifest, input);
+}
+/** Create a local tool with the same id and response shape as hosted `search_knowledge`. */
+export function createSearchKnowledgeTool(options = {}) {
+    const { id = "search_knowledge", description, ...config } = options;
+    return tool({
+        id,
+        description: description ??
+            "Retrieve a compact, cursor-based slice of the local project knowledge manifest.",
+        inputSchema: SEARCH_KNOWLEDGE_INPUT_SCHEMA,
+        execute: (input) => searchProjectKnowledge(coerceSearchKnowledgeInput(input), config),
+    });
+}
 /** Create a project knowledge helper backed by the configured RAG store. */
 export function projectKnowledge(config = {}) {
     const store = ragStore({
@@ -58,6 +456,9 @@ export function projectKnowledge(config = {}) {
     }
     return {
         index,
+        lookup(input) {
+            return searchProjectKnowledge(input, config);
+        },
         async retrieve(query, options) {
             const normalizedQuery = normalizeKnowledgeQuery(query, options?.maxQueryChars ?? config.maxQueryChars);
             if (!normalizedQuery)

package/esm/src/platform/compat/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Platform Compat
+ *
+ * @module platform/compat
+ */
+export { createFileSystem, exists, type FileSystem, isNotFoundError, makeTempDir, mkdir, readDir, readTextFile, remove, stat, symlink, writeFile, writeTextFile, } from "./fs.js";
+export { createKVStore, MemoryKv, openKv, polyfillDenoKv } from "./kv/index.js";
+export { SqliteKv } from "./kv/index.js";
+export type { Kv, KvEntry, KvListOptions, SqliteDatabase } from "./kv/index.js";
+export { chdir, cwd, deleteEnv, env, execPath, exit, getArgs, getEnv, getEnvBoolean, getEnvNumber, getEnvOverlayStorage, getEnvString, getOsType, getRuntimeVersion, getStdout, getTerminalSize, isInteractive, isStdoutTTY, memoryUsage, onGlobalError, onSignal, pid, promptSync, runCommand, setEnv, unrefTimer, uptime, writeStdout, writeStdoutAsync, } from "./process.js";
+export type { CommandOptions, CommandResult, EnvBooleanOptions } from "./process.js";
+export { isBrowserEnvironment, isBun, isCloudflare, isDeno, isDenoCompiled, isNode, isNodeRuntime, isServerEnvironment, } from "./runtime.js";
+export { createEscapeBuffer, type EscapeBuffer, getStdinReader, setRawMode, type StdinReader, waitForEnterOrExit, waitForKeypress, } from "./stdin.js";
+export { dynamicImport } from "./dynamic-import.js";
+export { importClaudeAgentSDK, importKreuzberg, importTransformers } from "./opaque-deps.js";
+export { basename, dirname, extname, fromFileUrl, isAbsolute, join, relative, resolve, sep, } from "./path/index.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/src/platform/compat/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/compat/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,gBAAgB,EAChB,MAAM,EACN,KAAK,UAAU,EACf,eAAe,EACf,WAAW,EACX,KAAK,EACL,OAAO,EACP,YAAY,EACZ,MAAM,EACN,IAAI,EACJ,OAAO,EACP,SAAS,EACT,aAAa,GACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGhF,OAAO,EACL,KAAK,EACL,GAAG,EACH,SAAS,EACT,GAAG,EACH,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,MAAM,EACN,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,aAAa,EACb,WAAW,EACX,WAAW,EACX,aAAa,EACb,QAAQ,EACR,GAAG,EACH,UAAU,EACV,UAAU,EACV,MAAM,EACN,UAAU,EACV,MAAM,EACN,WAAW,EACX,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGrF,OAAO,EACL,oBAAoB,EACpB,KAAK,EACL,YAAY,EACZ,MAAM,EACN,cAAc,EACd,MAAM,EACN,aAAa,EACb,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,cAAc,EACd,UAAU,EACV,KAAK,WAAW,EAChB,kBAAkB,EAClB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG7F,OAAO,EACL,QAAQ,EACR,OAAO,EACP,OAAO,EACP,WAAW,EACX,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,GAAG,GACJ,MAAM,iBAAiB,CAAC"}

package/esm/src/platform/compat/index.js

@@ -0,0 +1,22 @@
+/**
+ * Platform Compat
+ *
+ * @module platform/compat
+ */
+// Compat: filesystem
+export { createFileSystem, exists, isNotFoundError, makeTempDir, mkdir, readDir, readTextFile, remove, stat, symlink, writeFile, writeTextFile, } from "./fs.js";
+// Compat: KV store
+export { createKVStore, MemoryKv, openKv, polyfillDenoKv } from "./kv/index.js";
+export { SqliteKv } from "./kv/index.js";
+// Compat: process
+export { chdir, cwd, deleteEnv, env, execPath, exit, getArgs, getEnv, getEnvBoolean, getEnvNumber, getEnvOverlayStorage, getEnvString, getOsType, getRuntimeVersion, getStdout, getTerminalSize, isInteractive, isStdoutTTY, memoryUsage, onGlobalError, onSignal, pid, promptSync, runCommand, setEnv, unrefTimer, uptime, writeStdout, writeStdoutAsync, } from "./process.js";
+// Compat: runtime detection
+export { isBrowserEnvironment, isBun, isCloudflare, isDeno, isDenoCompiled, isNode, isNodeRuntime, isServerEnvironment, } from "./runtime.js";
+// Compat: stdin
+export { createEscapeBuffer, getStdinReader, setRawMode, waitForEnterOrExit, waitForKeypress, } from "./stdin.js";
+// Compat: dynamic import helper (hides specifiers from static analysis / deno compile)
+export { dynamicImport } from "./dynamic-import.js";
+// Compat: dynamic imports for optional deps (opaque) and platform-split deps (kreuzberg)
+export { importClaudeAgentSDK, importKreuzberg, importTransformers } from "./opaque-deps.js";
+// Compat: path
+export { basename, dirname, extname, fromFileUrl, isAbsolute, join, relative, resolve, sep, } from "./path/index.js";

package/esm/src/utils/version-constant.d.ts

@@ -1,3 +1,3 @@
 /** Shared version value. */
-export declare const VERSION = "0.1.934";
+export declare const VERSION = "0.1.936";
 //# sourceMappingURL=version-constant.d.ts.map

package/esm/src/utils/version-constant.js

@@ -1,4 +1,4 @@
 // Keep in sync with deno.json version.
 // scripts/release.ts updates this constant during releases.
 /** Shared version value. */
-export const VERSION = "0.1.934";
+export const VERSION = "0.1.936";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.934",
+  "version": "0.1.936",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",