functionalscript 0.30.0 → 0.31.0

package/fs/cas/mcp/proof.f.js

@@ -0,0 +1,310 @@
+import { assert, assertEq } from "../../asserts/module.f.js";
+import { pure } from "../../effects/module.f.js";
+import { run } from "../../effects/mock/module.f.js";
+import { asBase, asNominal, create, read, write } from "../../effects/memory/module.f.js";
+import { msb, u8ListToVec, vec8 } from "../../types/bit_vec/module.f.js";
+import { vecToCBase32 } from "../../cbase32/module.f.js";
+import { encode as base64Encode } from "../../base64/module.f.js";
+import { sha256 } from "../../crypto/sha2/module.f.js";
+import { utf8 } from "../../text/module.f.js";
+import { cas } from "../module.f.js";
+import { mcpStep, uninitializedState, } from "../../mcp/module.f.js";
+import {} from "../../effects/node/module.f.js";
+import { casConfig, casMcpHandlers } from "./module.f.js";
+const initialTestState = { memory: { next: 0, values: {} }, files: {} };
+const mock = {
+    memCreate: value => state => {
+        const id = `k${state.memory.next}`;
+        const key = asNominal(id);
+        return [
+            { ...state, memory: { next: state.memory.next + 1, values: { ...state.memory.values, [id]: value } } },
+            key,
+        ];
+    },
+    memRead: key => state => [state, state.memory.values[asBase(key)]],
+    memWrite: (key, value) => state => {
+        const id = asBase(key);
+        return [{ ...state, memory: { ...state.memory, values: { ...state.memory.values, [id]: value } } }, undefined];
+    },
+    readFile: path => state => {
+        const v = state.files[path];
+        return v !== undefined
+            ? [state, ['ok', v]]
+            : [state, ['error', new Error(`ENOENT: ${path}`)]];
+    },
+};
+const runMem = (effect) => run(mock)(initialTestState)(effect)[1];
+const runMemWithFiles = (files) => (effect) => run(mock)({ memory: { next: 0, values: {} }, files })(effect)[1];
+const memKvStore = (mapKey) => ({
+    read: (key) => read(mapKey).step(m => pure(m[vecToCBase32(key)]?.[1])),
+    write: (key, value) => read(mapKey).step(m => write(mapKey, { ...m, [vecToCBase32(key)]: [key, value] })),
+    list: () => read(mapKey).step(m => pure(Object.values(m).map(([k]) => k))),
+});
+// ── Session driver ──────────────────────────────────────────────────────────────
+// Feeds each message to `step` in order, collecting every response.
+const feed = (step) => (msgs) => {
+    const go = (i, acc) => i === msgs.length
+        ? pure(acc)
+        : step(msgs[i]).step(r => go(i + 1, [...acc, r]));
+    return go(0, []);
+};
+// Runs a full session over a fresh in-memory CAS, returning all responses.
+const runSession = (msgs) => runMem(create({}).step(mapKey => create(uninitializedState).step(sessionKey => {
+    const c = cas(sha256)(memKvStore(mapKey));
+    const step = mcpStep(casConfig)(casMcpHandlers(c))(sessionKey);
+    return feed(step)(msgs);
+})));
+// Runs a session with a mocked filesystem (for cas_add with type:'url' tests).
+const runSessionWithFiles = (files) => (msgs) => runMemWithFiles(files)(create({}).step(mapKey => create(uninitializedState).step(sessionKey => {
+    const c = cas(sha256)(memKvStore(mapKey));
+    const step = mcpStep(casConfig)(casMcpHandlers(c))(sessionKey);
+    return feed(step)(msgs);
+})));
+// ── Messages ────────────────────────────────────────────────────────────────────
+const init = { jsonrpc: '2.0', method: 'initialize', id: 1,
+    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'c', version: '0' } } };
+const initialized = { jsonrpc: '2.0', method: 'notifications/initialized' };
+const call = (id, name, args) => ({ jsonrpc: '2.0', method: 'tools/call', id, params: { name, arguments: args } });
+const list = (id) => ({ jsonrpc: '2.0', method: 'tools/list', id });
+// Runs `init`, `notifications/initialized`, then `msgs`; returns the tool responses.
+const session = (...msgs) => runSession([init, initialized, ...msgs]).slice(2);
+const resultOf = (resp) => resp.result;
+const item0 = (resp) => resultOf(resp).content[0];
+const textOf = (resp) => item0(resp).text;
+// A plain text sample for text add→get round-trips.
+const textSample = 'hello, world!';
+// A base64-encoded binary payload for binary add→get round-trips.
+const binarySample = base64Encode(vec8(0x2an));
+// A base64 blob whose leading bytes are the PNG magic-byte signature, so
+// `cas_get` detects its type and returns base64 with mime_type image/png.
+const pngSample = base64Encode(u8ListToVec(msb)([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01]));
+// ── Tests ───────────────────────────────────────────────────────────────────────
+export const proof = {
+    toolsListAdvertisesThreeTools: () => {
+        const [resp] = runSession([init, initialized, list(2)]).slice(2);
+        const tools = resp.result.tools;
+        assertEq(tools.length, 3);
+        assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list');
+        const add = resp.result.tools[0];
+        assertEq(add.inputSchema.type, 'object');
+    },
+    addReturnsHash: () => {
+        const [resp] = session(call(2, 'cas_add', { content: textSample }));
+        assert(!resultOf(resp).isError);
+        assert(textOf(resp).length > 0);
+    },
+    // Text add→get round-trip: store as UTF-8 text, retrieve metadata.
+    textAddGetMetaRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: textSample }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash }));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.mime_type, 'text/plain');
+        assertEq(result.type, 'text');
+        assertEq(result.length, textSample.length);
+        assertEq(result.content, undefined);
+    },
+    // cas_get with content:true returns inline content.
+    textAddGetContentRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: textSample }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.type, 'text');
+        assertEq(result.mime_type, 'text/plain');
+        assertEq(result.content, textSample);
+    },
+    // Binary add→get round-trip: store as base64, retrieve metadata without content.
+    binaryAddGetMetaRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }), call(3, 'cas_get', { hash }));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.content, undefined);
+        assertEq(result.type, 'text');
+        assertEq(result.mime_type, 'text/plain');
+    },
+    // Binary add→get with content:true returns inline base64 content.
+    binaryAddGetContentRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.type, 'text');
+        assertEq(result.content, '*');
+    },
+    addGetRoundTrips: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: textSample }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
+        assert(!resultOf(getResp).isError);
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.content, textSample);
+    },
+    // Text content (no magic-byte match, valid UTF-8) comes back with type:'text' when content requested.
+    getUntypedReturnsText: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: textSample }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
+        assertEq(item0(getResp) === null ? null : item0(getResp).type, 'text');
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.type, 'text');
+        assertEq(result.mime_type, 'text/plain');
+    },
+    // Bytes with a recognised PNG signature come back as base64 with mime_type image/png when content requested.
+    getTypedReturnsBinaryJson: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }));
+        const hash = textOf(addResp);
+        const [, getResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
+        assert(!resultOf(getResp).isError);
+        assertEq(item0(getResp).type, 'text');
+        const result = JSON.parse(textOf(getResp));
+        assertEq(result.type, 'base64');
+        assertEq(result.mime_type, 'image/png');
+        assertEq(result.content, pngSample);
+    },
+    listEnumeratesStoredHashes: () => {
+        const [addResp, listResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_list', {}));
+        const hash = textOf(addResp);
+        assert(!resultOf(listResp).isError);
+        assertEq(textOf(listResp), hash);
+    },
+    addInvalidContentIsError: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'not valid!', type: 'base64' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    addBadLengthContentIsError: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'A', type: 'base64' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getUnterminatedHashIsError: () => {
+        const [resp] = session(call(2, 'cas_get', { hash: '0' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    addMissingContentIsError: () => {
+        const [resp] = session(call(2, 'cas_add', {}));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getMissingHashArgumentIsError: () => {
+        const [resp] = session(call(2, 'cas_get', {}));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getInvalidHashIsError: () => {
+        const [resp] = session(call(2, 'cas_get', { hash: 'not valid!' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getMissingHashIsError: () => {
+        const absent = vecToCBase32(vec8(0x99n));
+        const [resp] = session(call(2, 'cas_get', { hash: absent }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    unknownToolIsError: () => {
+        const [resp] = session(call(2, 'cas_remove', { hash: binarySample }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    toolErrorIsNotJsonRpcError: () => {
+        const [resp] = session(call(2, 'cas_add', { content: 'not valid!', type: 'base64' }));
+        assert(!('error' in resp));
+        assert('result' in resp);
+    },
+    // cas_add with type:'url' reads a file and stores it.
+    addUrlStoresFileAndReturnsHash: () => {
+        const fileContent = utf8('hello from file');
+        const [addUrlResp] = runSessionWithFiles({ '/tmp/hello.txt': fileContent })([
+            init, initialized,
+            call(2, 'cas_add', { content: '/tmp/hello.txt', type: 'url' }),
+        ]).slice(2);
+        assert(!resultOf(addUrlResp).isError);
+        assert(textOf(addUrlResp).length > 0);
+    },
+    addUrlRoundTrips: () => {
+        const fileContent = utf8('round-trip content');
+        const msgs = runSessionWithFiles({ '/tmp/rt.txt': fileContent })([
+            init, initialized,
+            call(2, 'cas_add', { content: '/tmp/rt.txt', type: 'url' }),
+        ]).slice(2);
+        const hash = textOf(msgs[0]);
+        const msgs2 = runSessionWithFiles({ '/tmp/rt.txt': fileContent })([
+            init, initialized,
+            call(2, 'cas_add', { content: '/tmp/rt.txt', type: 'url' }),
+            call(3, 'cas_get', { hash, content: true }),
+        ]).slice(2);
+        assert(!resultOf(msgs2[1]).isError);
+        const result = JSON.parse(textOf(msgs2[1]));
+        assertEq(result.type, 'text');
+        assertEq(result.content, 'round-trip content');
+    },
+    addUrlMissingFileIsError: () => {
+        const [resp] = runSessionWithFiles({})([
+            init, initialized,
+            call(2, 'cas_add', { content: '/nonexistent/path.txt', type: 'url' }),
+        ]).slice(2);
+        assertEq(resultOf(resp).isError, true);
+    },
+    // cas_get without content:true returns only metadata.
+    getMetaReturnsLengthAndMimeType: () => {
+        const fileContent = utf8('text content');
+        const [addResp] = runSessionWithFiles({ '/f': fileContent })([
+            init, initialized,
+            call(2, 'cas_add', { content: '/f', type: 'url' }),
+        ]).slice(2);
+        const hash = textOf(addResp);
+        const [, metaResp2] = runSessionWithFiles({ '/f': fileContent })([
+            init, initialized,
+            call(2, 'cas_add', { content: '/f', type: 'url' }),
+            call(3, 'cas_get', { hash }),
+        ]).slice(2);
+        assert(!resultOf(metaResp2).isError);
+        const meta = JSON.parse(textOf(metaResp2));
+        assertEq(meta.mime_type, 'text/plain');
+        assertEq(meta.type, 'text');
+        assertEq(meta.length, Number(BigInt(/* 'text content'.length */ 12)));
+        assertEq(meta.content, undefined);
+    },
+    getMetaBinaryBlob: () => {
+        const [addResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }));
+        const hash = textOf(addResp);
+        const [, metaResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }), call(3, 'cas_get', { hash }));
+        assert(!resultOf(metaResp).isError);
+        const meta = JSON.parse(textOf(metaResp));
+        assertEq(meta.mime_type, 'image/png');
+        assertEq(meta.type, 'base64');
+        assertEq(meta.length, 10);
+        assertEq(meta.content, undefined);
+    },
+    getMetaOctetStreamForUnknownBinary: () => {
+        const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01]);
+        const binaryB64 = base64Encode(binaryContent);
+        const [addResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }));
+        const hash = textOf(addResp);
+        const [, metaResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }), call(3, 'cas_get', { hash }));
+        assert(!resultOf(metaResp).isError);
+        const meta = JSON.parse(textOf(metaResp));
+        assertEq(meta.mime_type, 'application/octet-stream');
+        assertEq(meta.type, 'base64');
+        assertEq(meta.content, undefined);
+    },
+    getMetaNoUrlWhenToUrlAbsent: () => {
+        const content = utf8('no url');
+        const binaryB64 = base64Encode(content);
+        const [addResp] = session(call(2, 'cas_add', { content: binaryB64 }));
+        const hash = textOf(addResp);
+        const [, metaResp] = session(call(2, 'cas_add', { content: binaryB64 }), call(3, 'cas_get', { hash }));
+        assert(!resultOf(metaResp).isError);
+        const meta = JSON.parse(textOf(metaResp));
+        assertEq(meta.url, undefined);
+    },
+    getMetaMissingHashIsError: () => {
+        const absent = vecToCBase32(vec8(0x77n));
+        const [resp] = session(call(2, 'cas_get', { hash: absent }));
+        assertEq(resultOf(resp).isError, true);
+    },
+    getMetaInvalidHashIsError: () => {
+        const [resp] = session(call(2, 'cas_get', { hash: 'bad!' }));
+        assertEq(resultOf(resp).isError, true);
+    },
+};

package/fs/cas/module.f.d.ts

@@ -6,7 +6,9 @@
 import { type Sha2 } from '../crypto/sha2/module.f.ts';
 import type { Vec } from '../types/bit_vec/module.f.ts';
 import { type Effect, type Operation } from '../effects/module.f.ts';
-import { type Fs, type NodeOp, type NodeProgramOptions } from '../effects/node/module.f.ts';
+import { type Access, type All, type Mkdir, type NodeProgramOptions, type Read, type Readdir, type ReadFile, type Write, type WriteFile } from '../effects/node/module.f.ts';
+import { type Commands } from '../cli/module.f.ts';
+import type { MemOp } from '../effects/memory/module.f.ts';
 export type KvStore<O extends Operation> = {
     /** Reads a value by key; returns `undefined` when the key does not exist. */
     readonly read: (key: Vec) => Effect<O, Vec | undefined>;
@@ -17,10 +19,13 @@ export type KvStore<O extends Operation> = {
 };
 /** A key/value tuple where index `0` is the key and index `1` is the value. */
 export type Kv = readonly [Vec, Vec];
+/** Converts a content key to its sharded relative CAS file path. */
+export declare const toPath: (key: Vec) => string;
+export type FileKvStoreOperation = ReadFile | Mkdir | WriteFile | Access | Readdir;
 /**
  * Creates a filesystem-backed key/value store under the provided root path.
  */
-export declare const fileKvStore: (path: string) => KvStore<Fs>;
+export declare const fileKvStore: (path: string) => KvStore<FileKvStoreOperation>;
 export type Cas<O extends Operation> = {
     /** Reads content by hash; returns `undefined` when not found. */
     readonly read: (key: Vec) => Effect<O, Vec | undefined>;
@@ -33,4 +38,5 @@ export type Cas<O extends Operation> = {
  * Builds a content-addressable storage facade from a SHA-2 implementation.
  */
 export declare const cas: (sha2: Sha2) => <O extends Operation>(_: KvStore<O>) => Cas<O>;
-export declare const main: (options: NodeProgramOptions) => Effect<NodeOp, number>;
+export declare const commands: Commands<FileKvStoreOperation | Write | All | MemOp | Read>;
+export declare const main: (options: NodeProgramOptions) => Effect<All | Read | Write | FileKvStoreOperation | MemOp, number>;

package/fs/cas/module.f.js

@@ -4,45 +4,70 @@
  * @module
  */
 import { computeSync, sha256 } from "../crypto/sha2/module.f.js";
-import { parse } from "../path/module.f.js";
+import { join, normalize, parse } from "../path/module.f.js";
 import { cBase32ToVec, vecToCBase32 } from "../cbase32/module.f.js";
 import { forEachStep, pure } from "../effects/module.f.js";
-import { errorExit, log, mkdir, readdir, readFile, writeFile } from "../effects/node/module.f.js";
+import { access, errorExit, isNotFound, log, mkdir, readdir, readFile, writeFile } from "../effects/node/module.f.js";
 import { dispatch } from "../cli/module.f.js";
+import { casMcpServer } from "./mcp/module.f.js";
 import { toOption } from "../types/nullable/module.f.js";
 import { unwrap } from "../types/result/module.f.js";
+import { splitAt } from "../types/string/module.f.js";
 const o = { withFileTypes: true };
-const split = (s) => [s.substring(0, 2), s.substring(2)];
+const split2 = splitAt(2);
 const prefix = '.cas';
 /** Converts a content key to its sharded relative CAS file path. */
-const toPath = (key) => {
+export const toPath = (key) => {
     const s = vecToCBase32(key);
-    const [a, bc] = split(s);
-    const [b, c] = split(bc);
-    return `${prefix}/${a}/${b}/${c}`;
+    const [a, bc] = split2(s);
+    const [b, c] = split2(bc);
+    return join(prefix, a, b, c);
 };
 /**
  * Creates a filesystem-backed key/value store under the provided root path.
  */
-export const fileKvStore = (path) => ({
-    read: (key) => readFile(toPath(key))
-        .step(([status, data]) => pure(status === 'error' ? undefined : data)),
-    write: (key, value) => {
-        const p = toPath(key);
-        const parts = parse(p);
-        const dir = `${path}/${parts.slice(0, -1).join('/')}`;
-        // TODO: error handling
-        return mkdir(dir, { recursive: true })
-            .step(() => writeFile(`${path}/${p}`, value))
-            .step(() => pure(undefined));
-    },
-    list: () => 
-    // TODO: remove unwrap
-    readdir('.cas', { recursive: true })
-        .step(r => pure(unwrap(r).flatMap(({ name, parentPath, isFile }) => toOption(isFile
-        ? cBase32ToVec(parentPath.substring(prefix.length).replaceAll('/', '') + name)
-        : null)))),
-});
+export const fileKvStore = (path) => {
+    const storePrefix = join(path, prefix);
+    const normalizedStorePrefix = normalize(storePrefix);
+    return {
+        read: (key) => readFile(join(path, toPath(key))).step(r => {
+            if (r[0] === 'ok') {
+                return pure(r[1]);
+            }
+            // A missing file means "no such content"; surface anything else.
+            if (isNotFound(r[1])) {
+                return pure(undefined);
+            }
+            throw r[1];
+        }),
+        write: (key, value) => {
+            const p = toPath(key);
+            const parts = parse(p);
+            const dir = join(path, ...parts.slice(0, -1));
+            // TODO: error handling
+            return mkdir(dir, { recursive: true })
+                .step(() => writeFile(join(path, p), value))
+                .step(() => pure(undefined));
+        },
+        list: () => 
+        // A fresh store has no `.cas` directory yet. Treat *only* that case as an
+        // empty store, mirroring how `read` maps a missing file to `undefined`.
+        // A `.cas` that exists but cannot be read (permissions, corruption) is a
+        // genuine storage error and is surfaced, not masked as "no hashes".
+        access(storePrefix).step(a => {
+            if (a[0] === 'error') {
+                if (isNotFound(a[1])) {
+                    return pure([]);
+                }
+                throw a[1];
+            }
+            return readdir(storePrefix, { recursive: true })
+                .step(r => pure(unwrap(r).flatMap(({ name, parentPath, isFile }) => toOption(isFile
+                ? cBase32ToVec(normalize(parentPath).substring(normalizedStorePrefix.length).replaceAll('/', '') + name)
+                : null))));
+        }),
+    };
+};
 /**
  * Builds a content-addressable storage facade from a SHA-2 implementation.
  */
@@ -58,50 +83,60 @@ export const cas = (sha2) => {
         list,
     });
 };
-export const main = (options) => {
-    const c = cas(sha256)(fileKvStore('.'));
-    const commands = [
-        {
-            names: ['add'],
-            description: 'Store file content and print its hash',
-            handler: ({ args: [path, ...rest] }) => {
-                if (path === undefined || rest.length !== 0) {
-                    return errorExit("'cas add' expects one parameter");
-                }
-                return readFile(path)
-                    .step(v => c.write(unwrap(v)))
-                    .step(hash => log(vecToCBase32(hash)))
-                    .step(() => pure(0));
-            },
+export const commands = [
+    {
+        names: ['add'],
+        description: 'Store file content and print its hash',
+        handler: ({ home, args: [path, ...rest] }) => {
+            if (path === undefined || rest.length !== 0) {
+                return errorExit("'cas add' expects one parameter");
+            }
+            const c = cas(sha256)(fileKvStore(home));
+            return readFile(path)
+                .step(v => c.write(unwrap(v)))
+                .step(hash => log(vecToCBase32(hash)))
+                .step(() => pure(0));
         },
-        {
-            names: ['get'],
-            description: 'Restore content by hash into a file',
-            handler: ({ args: [hashCBase32, path, ...rest] }) => {
-                if (hashCBase32 === undefined || path === undefined || rest.length !== 0) {
-                    return errorExit("'cas get' expects two parameters");
-                }
-                const hash = cBase32ToVec(hashCBase32);
-                if (hash === null) {
-                    return errorExit(`invalid hash format: ${hashCBase32}`);
-                }
-                return c.read(hash)
-                    .step(v => {
-                    const result = v === undefined
-                        ? errorExit(`no such hash: ${hashCBase32}`)
-                        : writeFile(path, v)
-                            .step(() => pure(0));
-                    return result;
-                });
-            },
+    },
+    {
+        names: ['get'],
+        description: 'Restore content by hash into a file',
+        handler: ({ home, args: [hashCBase32, path, ...rest] }) => {
+            if (hashCBase32 === undefined || path === undefined || rest.length !== 0) {
+                return errorExit("'cas get' expects two parameters");
+            }
+            const hash = cBase32ToVec(hashCBase32);
+            if (hash === null) {
+                return errorExit(`invalid hash format: ${hashCBase32}`);
+            }
+            const c = cas(sha256)(fileKvStore(home));
+            return c.read(hash)
+                .step(v => {
+                const result = v === undefined
+                    ? errorExit(`no such hash: ${hashCBase32}`)
+                    : writeFile(path, v)
+                        .step(() => pure(0));
+                return result;
+            });
         },
-        {
-            names: ['list'],
-            description: 'List all stored content hashes',
-            handler: () => c.list()
+    },
+    {
+        names: ['list'],
+        description: 'List all stored content hashes',
+        handler: ({ home }) => {
+            const c = cas(sha256)(fileKvStore(home));
+            return c.list()
                 .step(forEachStep(j => log(vecToCBase32(j))))
-                .step(() => pure(0)),
+                .step(() => pure(0));
         },
-    ];
-    return dispatch(commands)(options);
-};
+    },
+    {
+        names: ['mcp'],
+        description: 'Run an MCP server over stdio exposing the CAS as tools',
+        handler: ({ home }) => {
+            const c = cas(sha256)(fileKvStore(home));
+            return casMcpServer(c, hash => join(home, toPath(hash))).step(() => pure(0));
+        },
+    },
+];
+export const main = dispatch(commands);

package/fs/cas/proof.f.d.ts

@@ -6,6 +6,8 @@ export declare const proof: {
     mainGetWrongArgs: () => void;
     mainGetInvalidHash: () => void;
     mainList: () => void;
+    mainListEmptyStore: () => void;
+    mainListCorruptStore: () => void;
     mainNoCmd: () => void;
     mainUnknownCmd: () => void;
     casWrite: () => void;

package/fs/cas/proof.f.js

@@ -1,18 +1,21 @@
-import { cas, main } from "./module.f.js";
+import { cas, commands } from "./module.f.js";
 import { sha256 } from "../crypto/sha2/module.f.js";
 import { empty, length, vec8 } from "../types/bit_vec/module.f.js";
 import { pure } from "../effects/module.f.js";
 import { run } from "../effects/mock/module.f.js";
 import { emptyState, virtual } from "../effects/node/virtual/module.f.js";
+import { dispatch } from "../cli/module.f.js";
 const makeOptions = (args) => ({
     args,
     env: {},
+    home: '.',
     std: { stdout: { isTTY: false }, stderr: { isTTY: false } },
     testContext: { test: async () => { } },
     bunTestContext: { test: async () => { } },
     playwrightTestContext: { test: async () => { } },
     engine: 'node',
 });
+const main = dispatch(commands);
 export const proof = {
     mainAdd: () => {
         const content = vec8(0x2an);
@@ -89,6 +92,32 @@ export const proof = {
             throw ['expected exit 0', exitCode];
         }
     },
+    mainListEmptyStore: () => {
+        // A fresh directory has no `.cas` yet; listing must succeed (empty),
+        // not crash unwrapping a readdir ENOENT.
+        const [finalState, exitCode] = virtual(emptyState)(main(makeOptions(['list'])));
+        if (exitCode !== 0) {
+            throw ['expected exit 0', exitCode];
+        }
+        if (finalState.stdout !== '') {
+            throw ['expected empty stdout', finalState.stdout];
+        }
+    },
+    mainListCorruptStore: () => {
+        // `.cas` exists but is a file, not a directory: a real storage error
+        // that must surface, not be masked as an empty list.
+        const state = { ...emptyState, root: { '.cas': vec8(0x2an) } };
+        let threw = false;
+        try {
+            virtual(state)(main(makeOptions(['list'])));
+        }
+        catch {
+            threw = true;
+        }
+        if (!threw) {
+            throw 'expected list to surface the storage error';
+        }
+    },
     mainNoCmd: () => {
         const [finalState, exitCode] = virtual(emptyState)(main(makeOptions([])));
         if (exitCode !== 1) {

package/fs/cbase32/module.f.d.ts

@@ -6,6 +6,6 @@
 import { type Vec } from "../types/bit_vec/module.f.ts";
 import type { Nullable } from "../types/nullable/module.f.ts";
 export declare const vec5xToCBase32: (v: Vec) => string;
-export declare const vecToCBase32: (v: Vec) => string;
 export declare const cBase32ToVec5x: (s: string) => Nullable<Vec>;
+export declare const vecToCBase32: (v: Vec) => string;
 export declare const cBase32ToVec: (s: string) => Nullable<Vec>;