@liquidmetal-ai/precip 1.0.0

package/src/mounts/mount-manager.ts

@@ -0,0 +1,327 @@
+/**
+ * Mount Manager - Routes path prefixes to Raindrop resources
+ *
+ * Supports mounting Buckets, SmartBuckets, KvCache, SqlDatabase, and Actors with path prefixes.
+ * All mounts require an explicit type field - no automatic type detection.
+ *
+ * Examples:
+ * - @user-data/profile.json → USER_BUCKET.get("profile.json")
+ * - @logs/2024/jan.txt → LOG_BUCKET.get("2024/jan.txt")
+ * - @knowledge/query → SMART_BUCKET.search({input: "query"})
+ * - sql:analytics → ANALYTICS_DB
+ * - kv:cache → CACHE_KV
+ * - actor:session → SESSION_ACTOR (accessed via actor.get('session', 'instance-name'))
+ */
+
+import type {
+  Logger,
+  MountConfig,
+  MountInfo,
+  ActorMountInfo,
+  ParsedPath,
+  MountProvider
+} from '../types.js';
+import { zodToTypeString } from './zod-to-string.js';
+import { createMountInfo, registerStandardMountTypes } from './mount-registry.js';
+
+// Initialize standard mount types on module load
+registerStandardMountTypes();
+
+export class MountManager implements MountProvider {
+  private mounts = new Map<string, MountInfo>();
+  private logger?: Logger;
+
+  constructor(config: MountConfig = {}, logger?: Logger) {
+    this.logger = logger;
+
+    for (const [name, input] of Object.entries(config)) {
+      this.mountConfig(name, input);
+    }
+  }
+
+  /**
+   * Mount a configuration (discriminated union with explicit type)
+   */
+  private mountConfig(name: string, config: MountConfig[string]): void {
+    // Use registry to create mount info
+    const info = createMountInfo(name, config);
+    this.mounts.set(name, info);
+  }
+
+  /**
+   * Unmount a resource
+   */
+  unmount(name: string): boolean {
+    return this.mounts.delete(name);
+  }
+
+  /**
+   * Get mount by name
+   */
+  getMount(name: string): MountInfo | undefined {
+    return this.mounts.get(name);
+  }
+
+  /**
+   * Get all mounts
+   */
+  getAllMounts(): Map<string, MountInfo> {
+    return new Map(this.mounts);
+  }
+
+  /**
+   * Parse a path to extract mount name and resource path
+   *
+   * Format: /mount-name/path/to/resource
+   * Examples:
+   *   /uploads/images/photo.jpg → { mountName: 'uploads', path: 'images/photo.jpg' }
+   *   /cache/user:123 → { mountName: 'cache', path: 'user:123' }
+   *   /analytics → { mountName: 'analytics', path: '' }
+   */
+  parsePath(fullPath: string): ParsedPath {
+    // Must start with /
+    if (!fullPath.startsWith('/')) {
+      throw new Error(`Invalid path: ${fullPath}. Paths must start with /`);
+    }
+
+    const withoutSlash = fullPath.slice(1);
+
+    if (withoutSlash === '') {
+      throw new Error(`Invalid path: ${fullPath}. Mount name required.`);
+    }
+
+    const slashIndex = withoutSlash.indexOf('/');
+
+    if (slashIndex === -1) {
+      // Just /mount-name with no path
+      return { mountName: withoutSlash, path: '', fullPath };
+    }
+
+    const mountName = withoutSlash.slice(0, slashIndex);
+    const path = withoutSlash.slice(slashIndex + 1);
+
+    return { mountName, path, fullPath };
+  }
+
+  /**
+   * Resolve a path to a mount and resource path
+   */
+  resolvePath(fullPath: string): { mount: MountInfo; path: string } {
+    const parsed = this.parsePath(fullPath);
+    const mount = this.mounts.get(parsed.mountName);
+
+    if (!mount) {
+      throw new Error(
+        `Mount not found: ${parsed.mountName}. Available mounts: ${Array.from(this.mounts.keys()).join(', ')}`
+      );
+    }
+
+    return { mount, path: parsed.path };
+  }
+
+  /**
+   * List all mounts by type
+   */
+  getMountsByType<T extends MountInfo['type']>(type: T): MountInfo[] {
+    return Array.from(this.mounts.values()).filter(m => m.type === type);
+  }
+
+  /**
+   * Get all actor mounts with their schemas
+   */
+  getActorMounts(): Map<string, ActorMountInfo> {
+    const actorMounts = new Map<string, ActorMountInfo>();
+    for (const [name, mount] of this.mounts) {
+      if (mount.type === 'actor') {
+        actorMounts.set(name, mount);
+      }
+    }
+    return actorMounts;
+  }
+
+  /**
+   * Create sandbox globals from mounts
+   * Returns globals that can be injected into QuickJS sandbox
+   */
+  createSandboxGlobals(): Record<string, any> {
+    const globals: Record<string, any> = {};
+
+    // Create bucket global with all bucket and smartbucket mounts
+    const bucketMounts = [
+      ...this.getMountsByType('bucket'),
+      ...this.getMountsByType('smartbucket')
+    ];
+    if (bucketMounts.length > 0) {
+      globals.bucket = {
+        // These will be replaced with actual async functions by the tool
+        _mounts: bucketMounts.map(m => ({ name: m.name, type: m.type })),
+        _type: 'bucket'
+      };
+    }
+
+    // Create kv global with all KV mounts
+    const kvMounts = this.getMountsByType('kv');
+    if (kvMounts.length > 0) {
+      globals.kv = {
+        _mounts: kvMounts.map(m => m.name),
+        _type: 'kv'
+      };
+    }
+
+    // Create db global with all database mounts
+    const dbMounts = this.getMountsByType('database');
+    if (dbMounts.length > 0) {
+      globals.db = {
+        _mounts: dbMounts.map(m => m.name),
+        _type: 'database'
+      };
+    }
+
+    // Create actor global placeholder (will be replaced by actor bridge)
+    const actorMounts = this.getActorMounts();
+    if (actorMounts.size > 0) {
+      globals.actor = {
+        _mounts: Array.from(actorMounts.entries()).map(([name, mount]) => ({
+          name,
+          methods: Object.keys(mount.methods)
+        })),
+        _type: 'actor'
+      };
+    }
+
+    // Create actor-storage placeholder (will be handled by storage bridge)
+    const actorStorageMounts = this.getMountsByType('actor-storage');
+    if (actorStorageMounts.length > 0) {
+      globals.actorStorage = {
+        _mounts: actorStorageMounts.map(m => m.name),
+        _type: 'actor-storage'
+      };
+    }
+
+    return globals;
+  }
+
+  /**
+   * Generate a formatted description of all mounts for inclusion in system prompts
+   * Returns a structured string that describes available resources
+   */
+  getMountsDescription(): string {
+    if (this.mounts.size === 0) {
+      return '';
+    }
+
+    const lines: string[] = [];
+
+    // Header
+    lines.push('');
+    lines.push('AVAILABLE STORAGE:');
+    lines.push('');
+    lines.push('All paths start with /<mount-name>/. Use these functions:');
+    lines.push('');
+
+    // Group by type
+    const bucketMounts = this.getMountsByType('bucket');
+    const smartbucketMounts = this.getMountsByType('smartbucket');
+    const kvMounts = this.getMountsByType('kv');
+    const dbMounts = this.getMountsByType('database');
+    const actorMounts = Array.from(this.getActorMounts().values());
+    const actorStorageMounts = this.getMountsByType('actor-storage');
+
+    // File storage (buckets and smartbuckets)
+    const allFileMounts = [...bucketMounts, ...smartbucketMounts];
+    if (allFileMounts.length > 0) {
+      lines.push('## File Storage');
+      lines.push('Durable object storage for files and binary data.');
+      lines.push('read() returns Response-like with .body (stream), .size, .uploaded');
+      lines.push('write() accepts optional { contentType, customMetadata }');
+      lines.push('');
+      for (const mount of allFileMounts) {
+        const desc = mount.description ? ` - ${mount.description}` : '';
+        const mode = mount.mode === 'rw' ? ' (read-write)' : ' (read-only)';
+        const isSmartBucket = mount.type === 'smartbucket';
+        lines.push(`  /${mount.name}/...${desc}${mode}${isSmartBucket ? ' [searchable]' : ''}`);
+      }
+      lines.push('');
+    }
+
+    // KV storage
+    if (kvMounts.length > 0) {
+      lines.push('## Key-Value Cache');
+      lines.push('Ephemeral key-value storage with optional expiration. Eventually consistent.');
+      lines.push('write() accepts optional { ttl, expiration, metadata }');
+      lines.push('');
+      for (const mount of kvMounts) {
+        const desc = mount.description ? ` - ${mount.description}` : '';
+        const mode = mount.mode === 'rw' ? ' (read-write)' : ' (read-only)';
+        lines.push(`  /${mount.name}/<key>${desc}${mode}`);
+      }
+      lines.push('');
+    }
+
+    // Actor storage
+    if (actorStorageMounts.length > 0) {
+      lines.push('## Actor State');
+      lines.push('Strongly consistent, transactional storage local to this actor instance.');
+      lines.push('list() supports range queries: { start, end, startAfter, reverse, limit }');
+      lines.push('');
+      for (const mount of actorStorageMounts) {
+        const desc = mount.description ? ` - ${mount.description}` : '';
+        const mode = mount.mode === 'rw' ? ' (read-write)' : ' (read-only)';
+        lines.push(`  /${mount.name}/<key>${desc}${mode}`);
+      }
+      lines.push('');
+    }
+
+    // Databases
+    if (dbMounts.length > 0) {
+      lines.push('## Databases');
+      lines.push('Use query() and execute() with these mounts:');
+      lines.push('');
+      for (const mount of dbMounts) {
+        const desc = mount.description ? ` - ${mount.description}` : '';
+        const mode = mount.mode === 'rw' ? ' (read-write)' : ' (read-only)';
+        lines.push(`  /${mount.name}${desc}${mode}`);
+      }
+      lines.push('');
+    }
+
+    // Actors
+    if (actorMounts.length > 0) {
+      lines.push('## Actors');
+      lines.push('Use actor(path, instanceId) to get a stub, then call methods.');
+      lines.push('');
+
+      for (const mount of actorMounts) {
+        const desc = mount.description ? ` - ${mount.description}` : '';
+        lines.push(`### /${mount.name}${desc}`);
+        lines.push('');
+        lines.push('Methods:');
+
+        for (const [methodName, schema] of Object.entries(mount.methods)) {
+          // Format tuple params as a function signature using .describe() for names
+          const tupleItems = (schema.params as any)._def?.items ?? [];
+          const paramsStr = tupleItems.length === 0
+            ? ''
+            : tupleItems.map((item: any, i: number) => {
+                const name = item.description ?? `arg${i}`;
+                return `${name}: ${zodToTypeString(item)}`;
+              }).join(', ');
+          const returnsStr = zodToTypeString(schema.returns);
+          lines.push(`  ${methodName}(${paramsStr}) → ${returnsStr}`);
+          lines.push(`    ${schema.description}`);
+        }
+
+        lines.push('');
+        lines.push('Example:');
+        lines.push(`  const stub = await actor("/${mount.name}", "<instance-id>");`);
+        const firstMethod = Object.keys(mount.methods)[0];
+        if (firstMethod) {
+          lines.push(`  const result = await stub.${firstMethod}(...);`);
+        }
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+}

package/src/mounts/mount-registry.ts

@@ -0,0 +1,196 @@
+/**
+ * Mount Registry - Extensible mount type system
+ *
+ * Replaces repetitive switch statements with a registration-based pattern.
+ * Makes it easy to add new mount types without modifying core code.
+ */
+
+import type {
+  BucketMountConfig,
+  SmartBucketMountConfig,
+  KvMountConfig,
+  SqlMountConfig,
+  ActorMountConfig,
+  ActorStorageMountConfig,
+  BucketMountInfo,
+  SmartBucketMountInfo,
+  KvMountInfo,
+  SqlMountInfo,
+  ActorMountInfo,
+  ActorStorageMountInfo,
+  MountConfigType,
+  MountInfo,
+  MountType,
+  MountMode
+} from '../types.js';
+
+// Internal base interfaces (not exported)
+interface BaseMountConfig {
+  description?: string;
+  mode?: MountMode;
+}
+
+interface BaseMountInfo extends BaseMountConfig {
+  name: string;
+}
+
+/**
+ * Handler for a specific mount type
+ */
+interface MountHandler<TConfig extends BaseMountConfig, TInfo extends BaseMountInfo> {
+  /** Validate the mount configuration */
+  validate?: (config: TConfig) => void;
+
+  /** Create a MountInfo from a name and config */
+  createInfo: (name: string, config: TConfig) => TInfo;
+}
+
+const mountHandlers = new Map<MountType, MountHandler<any, any>>();
+
+/**
+ * Register a mount type handler
+ */
+export function registerMountType<TConfig extends BaseMountConfig & { type: MountType }, TInfo extends BaseMountInfo>(
+  type: MountType,
+  handler: MountHandler<TConfig, TInfo>
+): void {
+  mountHandlers.set(type, handler);
+}
+
+/**
+ * Register standard mount types
+ */
+export function registerStandardMountTypes(): void {
+  // Bucket
+  registerMountType<BucketMountConfig, BucketMountInfo>('bucket', {
+    validate: (config) => {
+      if (!config.resource) {
+        throw new Error(`Bucket mount requires a resource`);
+      }
+    },
+    createInfo: (name, config) => ({
+      name,
+      type: 'bucket',
+      resource: config.resource,
+      description: config.description,
+      mode: config.mode
+    })
+  });
+
+  // SmartBucket
+  registerMountType<SmartBucketMountConfig, SmartBucketMountInfo>('smartbucket', {
+    validate: (config) => {
+      if (!config.resource) {
+        throw new Error(`SmartBucket mount requires a resource`);
+      }
+    },
+    createInfo: (name, config) => ({
+      name,
+      type: 'smartbucket',
+      resource: config.resource,
+      description: config.description,
+      mode: config.mode
+    })
+  });
+
+  // KvCache
+  registerMountType<KvMountConfig, KvMountInfo>('kv', {
+    validate: (config) => {
+      if (!config.resource) {
+        throw new Error(`KvCache mount requires a resource`);
+      }
+    },
+    createInfo: (name, config) => ({
+      name,
+      type: 'kv',
+      resource: config.resource,
+      description: config.description,
+      mode: config.mode
+    })
+  });
+
+  // SqlDatabase
+  registerMountType<SqlMountConfig, SqlMountInfo>('database', {
+    validate: (config) => {
+      if (!config.resource) {
+        throw new Error(`Database mount requires a resource`);
+      }
+    },
+    createInfo: (name, config) => ({
+      name,
+      type: 'database',
+      resource: config.resource,
+      description: config.description,
+      mode: config.mode
+    })
+  });
+
+  // Actor
+  registerMountType<ActorMountConfig, ActorMountInfo>('actor', {
+    validate: (config) => {
+      if (!config.resource) {
+        throw new Error(`Actor mount requires a resource`);
+      }
+      if (!config.methods || Object.keys(config.methods).length === 0) {
+        throw new Error(`Actor mount requires at least one method schema`);
+      }
+    },
+    createInfo: (name, config) => ({
+      name,
+      type: 'actor',
+      resource: config.resource,
+      description: config.description,
+      mode: config.mode,
+      methods: config.methods
+    })
+  });
+
+  // ActorStorage
+  registerMountType<ActorStorageMountConfig, ActorStorageMountInfo>('actor-storage', {
+    validate: (config) => {
+      if (!config.resource) {
+        throw new Error(`ActorStorage mount requires a resource`);
+      }
+    },
+    createInfo: (name, config) => ({
+      name,
+      type: 'actor-storage',
+      resource: config.resource,
+      description: config.description,
+      mode: config.mode
+    })
+  });
+}
+
+/**
+ * Create a MountInfo from a name and config
+ */
+export function createMountInfo(name: string, config: MountConfigType): MountInfo {
+  const handler = mountHandlers.get(config.type);
+
+  if (!handler) {
+    throw new Error(`Unknown mount type: ${config.type}`);
+  }
+
+  // Validate if handler provides validation
+  if (handler.validate) {
+    handler.validate(config);
+  }
+
+  // Create the mount info
+  return handler.createInfo(name, config);
+}
+
+/**
+ * Get all registered mount types
+ */
+export function getRegisteredMountTypes(): MountType[] {
+  return Array.from(mountHandlers.keys());
+}
+
+/**
+ * Check if a mount type is registered
+ */
+export function isMountTypeRegistered(type: MountType): boolean {
+  return mountHandlers.has(type);
+}

package/src/mounts/zod-to-string.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Tests for zodToTypeString utility
+ */
+
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { zodToTypeString } from './zod-to-string.js';
+
+describe('zodToTypeString', () => {
+  describe('primitives', () => {
+    it('should convert z.string() to "string"', () => {
+      expect(zodToTypeString(z.string())).toBe('string');
+    });
+
+    it('should convert z.number() to "number"', () => {
+      expect(zodToTypeString(z.number())).toBe('number');
+    });
+
+    it('should convert z.boolean() to "boolean"', () => {
+      expect(zodToTypeString(z.boolean())).toBe('boolean');
+    });
+
+    it('should convert z.null() to "null"', () => {
+      expect(zodToTypeString(z.null())).toBe('null');
+    });
+
+    it('should convert z.undefined() to "undefined"', () => {
+      expect(zodToTypeString(z.undefined())).toBe('undefined');
+    });
+  });
+
+  describe('literals and enums', () => {
+    it('should convert z.literal("hello") to "\'hello\'"', () => {
+      expect(zodToTypeString(z.literal('hello'))).toBe("'hello'");
+    });
+
+    it('should convert z.literal(42) to "42"', () => {
+      expect(zodToTypeString(z.literal(42))).toBe('42');
+    });
+
+    it('should convert z.enum to union of literals', () => {
+      const result = zodToTypeString(z.enum(['light', 'dark']));
+      expect(result).toBe("'light' | 'dark'");
+    });
+  });
+
+  describe('arrays', () => {
+    it('should convert z.array(z.string()) to "Array<string>"', () => {
+      expect(zodToTypeString(z.array(z.string()))).toBe('Array<string>');
+    });
+
+    it('should convert z.array(z.number()) to "Array<number>"', () => {
+      expect(zodToTypeString(z.array(z.number()))).toBe('Array<number>');
+    });
+  });
+
+  describe('objects', () => {
+    it('should convert empty z.object({}) to "{}"', () => {
+      expect(zodToTypeString(z.object({}))).toBe('{}');
+    });
+
+    it('should convert simple object', () => {
+      const schema = z.object({ name: z.string() });
+      expect(zodToTypeString(schema)).toBe('{ name: string }');
+    });
+
+    it('should convert object with multiple properties', () => {
+      const schema = z.object({
+        name: z.string(),
+        age: z.number()
+      });
+      expect(zodToTypeString(schema)).toBe('{ name: string, age: number }');
+    });
+
+    it('should mark optional properties', () => {
+      const schema = z.object({
+        name: z.string(),
+        age: z.number().optional()
+      });
+      expect(zodToTypeString(schema)).toBe('{ name: string, age?: number }');
+    });
+  });
+
+  describe('unions', () => {
+    it('should convert z.union to pipe-separated types', () => {
+      const schema = z.union([z.string(), z.number()]);
+      expect(zodToTypeString(schema)).toBe('string | number');
+    });
+  });
+
+  describe('optional and nullable', () => {
+    it('should unwrap optional', () => {
+      expect(zodToTypeString(z.string().optional())).toBe('string');
+    });
+
+    it('should show nullable as union with null', () => {
+      expect(zodToTypeString(z.string().nullable())).toBe('string | null');
+    });
+  });
+
+  describe('records and maps', () => {
+    it('should convert z.record to Record<string, T>', () => {
+      expect(zodToTypeString(z.record(z.number()))).toBe('Record<string, number>');
+    });
+  });
+
+  describe('tuples', () => {
+    it('should convert z.tuple to bracketed types', () => {
+      const schema = z.tuple([z.string(), z.number()]);
+      expect(zodToTypeString(schema)).toBe('[string, number]');
+    });
+  });
+
+  describe('complex nested types', () => {
+    it('should handle nested objects', () => {
+      const schema = z.object({
+        user: z.object({
+          name: z.string()
+        })
+      });
+      const result = zodToTypeString(schema);
+      expect(result).toContain('user');
+    });
+
+    it('should handle array of objects', () => {
+      const schema = z.array(z.object({ id: z.string() }));
+      expect(zodToTypeString(schema)).toBe('Array<{ id: string }>');
+    });
+  });
+
+  describe('depth limiting', () => {
+    it('should abbreviate deeply nested types', () => {
+      // Create a deeply nested structure
+      const deep = z.object({
+        a: z.object({
+          b: z.object({
+            c: z.object({
+              d: z.object({
+                e: z.object({
+                  f: z.string()
+                })
+              })
+            })
+          })
+        })
+      });
+
+      const result = zodToTypeString(deep);
+      // Should not throw and should return something reasonable
+      expect(result).toBeDefined();
+      expect(result.length).toBeLessThan(500); // Shouldn't explode
+    });
+  });
+});