@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/layout/state.svelte.js

@@ -0,0 +1,92 @@
+import { readLayoutPreference, writeLayoutPreference, uncapturedLayoutFailure } from "./runtime.js";
+class LayoutStateModel {
+    host;
+    sidebarLeftOpen = $state(true);
+    initialized = $state(false);
+    lastReadResult = $state(null);
+    lastWriteResult = $state(null);
+    disposed = false;
+    constructor(host) {
+        this.host = host;
+    }
+    /** Idempotent until disposal. A persisted value overrides the caller's default. */
+    init = (options = {}) => {
+        if (this.disposed) {
+            this.lastReadResult = this.disposedResult();
+            return;
+        }
+        if (this.initialized)
+            return;
+        const defaultOpen = options.defaultSidebarLeftOpen;
+        if (defaultOpen === true || defaultOpen === false)
+            this.sidebarLeftOpen = defaultOpen;
+        const result = readLayoutPreference(this.host);
+        this.lastReadResult = result;
+        if (result.status === 'found')
+            this.sidebarLeftOpen = result.value;
+        this.initialized = true;
+    };
+    setSidebarLeftOpen = (open) => {
+        if (this.disposed) {
+            this.lastWriteResult = this.disposedResult();
+            return;
+        }
+        this.lastWriteResult = writeLayoutPreference(this.host, open);
+        if (open === true || open === false)
+            this.sidebarLeftOpen = open;
+    };
+    toggleSidebarLeft = () => {
+        this.setSidebarLeftOpen(!this.sidebarLeftOpen);
+    };
+    /** Ends this view without clearing storage or disposing the borrowed host. */
+    dispose = () => {
+        this.disposed = true;
+        this.sidebarLeftOpen = true;
+        this.initialized = false;
+        this.lastReadResult = null;
+        this.lastWriteResult = null;
+    };
+    disposedResult() {
+        return {
+            status: 'refused',
+            code: 'CANCELLED',
+            reason: 'layout-adapter-disposed'
+        };
+    }
+}
+export function createLayoutState(host) {
+    return new LayoutStateModel(host);
+}
+/** Compatibility name only. A captured adapter supplies the usable root-bound state. */
+export const layoutState = Object.freeze({
+    get sidebarLeftOpen() {
+        throw uncapturedLayoutFailure();
+    },
+    set sidebarLeftOpen(_open) {
+        throw uncapturedLayoutFailure();
+    },
+    get initialized() {
+        throw uncapturedLayoutFailure();
+    },
+    set initialized(_initialized) {
+        throw uncapturedLayoutFailure();
+    },
+    get lastReadResult() {
+        throw uncapturedLayoutFailure();
+    },
+    get lastWriteResult() {
+        throw uncapturedLayoutFailure();
+    },
+    init(_options) {
+        throw uncapturedLayoutFailure();
+    },
+    setSidebarLeftOpen(_open) {
+        throw uncapturedLayoutFailure();
+    },
+    toggleSidebarLeft() {
+        throw uncapturedLayoutFailure();
+    },
+    dispose() {
+        throw uncapturedLayoutFailure();
+    }
+});

package/dist/layout/styles.css

@@ -0,0 +1,10 @@
+/*
+ * Tailwind v4 source declaration for consumers — mirrors @vibesdotdev/kit's
+ * styles.css pattern. Apps that @import this file get this package's
+ * components scanned by their Tailwind build, so utility classes used only
+ * inside these components are emitted in the app's CSS bundle. Without it,
+ * such classes are missing per-app by lottery (Tailwind never scans
+ * node_modules). Paths resolve relative to this file: dist/layout/styles.css at
+ * runtime, src/layout/styles.css under the bun condition.
+ */
+@source './';

package/dist/layout/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared TypeScript types for `@vibesdotdev/kit/layout`.
+ *
+ * Kept in a rune-free module so `bun test` and downstream consumers can
+ * import types without pulling in `state.svelte.ts` (which is not evaluable
+ * outside the Svelte compiler).
+ */
+import type { Component, Snippet } from 'svelte';
+/**
+ * Props for `<SidebarPanel>`. Pure-presentation chrome around four snippet
+ * slots (`content`, `footer`, `headerActions`, `menuContent`). No domain
+ * coupling - consumers wire their own content.
+ */
+export interface SidebarPanelProps {
+    /** Header title shown next to the optional icon. */
+    title: string;
+    /** Optional icon component rendered before the title. */
+    icon?: Component<{
+        class?: string;
+    }>;
+    /** When provided, renders a close button in the header. */
+    onClose?: () => void;
+    /** Main body slot. */
+    content?: Snippet;
+    /** Optional footer slot (renders only when present). */
+    footer?: Snippet;
+    /** Extra actions rendered in the header bar (before the close button). */
+    headerActions?: Snippet;
+    /** Context-menu items; wraps the body in a `<ContextMenu>` trigger. */
+    menuContent?: Snippet;
+}

package/dist/layout/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared TypeScript types for `@vibesdotdev/kit/layout`.
+ *
+ * Kept in a rune-free module so `bun test` and downstream consumers can
+ * import types without pulling in `state.svelte.ts` (which is not evaluable
+ * outside the Svelte compiler).
+ */
+export {};

package/dist/lib/README.md

@@ -0,0 +1,417 @@
+# VibesKit - Delightful API Development
+
+**A comprehensive, secure-by-default API wrapper system that makes building APIs a joy.**
+
+VibesKit centralizes all API concerns into a clean, composable system with working implementations for authentication, rate limiting, caching, billing, and validation.
+
+## Features
+
+### ✅ Working Features (Not Placeholders)
+
+- **Authentication & Authorization**: Role-based access control with permission checking
+- **Rate Limiting**: Token bucket rate limiting with Redis persistence
+- **Caching**: Redis-based caching with configurable TTL
+- **Billing Integration**: Feature access and quota checking
+- **Validation**: Zod-based request/response validation
+- **OpenAPI Generation**: Automatic API documentation
+- **Performance Monitoring**: Request timing and metrics
+- **Error Handling**: Structured error responses
+- **Logging**: Comprehensive request/response logging
+
+### 🎯 Design Philosophy
+
+- **Working Implementations**: All features are fully functional, not configuration placeholders
+- **Sensible Defaults**: Preconfigured common patterns that can be overridden
+- **Type Safety**: Full TypeScript support with schema-driven development
+- **Composable**: Mix and match features as needed
+- **Performance**: Built-in caching and rate limiting
+- **Developer Experience**: Clean, intuitive API
+
+## Quick Start
+
+```typescript
+import { vibesGET, vibesPOST, auth, cache, quick } from '$lib/vibeskit';
+
+// Simple authenticated endpoint
+export const GET = vibesGET(
+\t{ ...quick.auth() },
+\tasync (event, context) => {
+\t\treturn { message: 'Hello authenticated user!', user: context.user };
+\t}
+);
+
+// More advanced endpoint with custom configuration
+export const POST = vibesPOST(
+\t{
+\t\tmetadata: {
+\t\t\tsummary: 'Create a new item',
+\t\t\ttags: ['Items']
+\t\t},
+\t\tauth: auth.permissions(['item:create']),
+\t\trateLimit: rateLimitPatterns.standard(),
+\t\t		caching: cache.none(), // Don't cache mutations
+\t\tbilling: billing.credits('api-calls', 1),
+\t\tvalidation: {
+\t\t\tbody: body.nameDescription,
+\t\t\tparams: params.projectId
+\t\t}
+\t},
+\tasync (event, context) => {
+\t\tconst { name, description } = context.validated.body;
+\t\t// Your business logic here
+\t\treturn { success: true, item: { name, description } };
+\t}
+);
+```
+
+## Helper Functions
+
+### Authentication Helpers
+
+```typescript
+import { auth } from '$lib/vibeskit';
+
+// Simple auth requirement
+auth.required();
+
+// Permission requirements
+auth.permissions(['chat:write', 'chat:read']);
+
+// Admin only access
+auth.adminOnly();
+
+// Role requirements
+auth.roles(['moderator', 'admin']);
+```
+
+### Rate Limiting Helpers
+
+```typescript
+import { rateLimit } from '$lib/vibeskit';
+
+// Predefined limits
+rateLimit.standard(); // 10/min, 100/hour
+rateLimit.strict(); // 1/min, 10/hour
+rateLimit.generous(); // 60/min, 1000/hour
+
+// Custom limits
+rateLimit.custom({ rpm: 20, rph: 200 });
+
+// User-specific rate limiting
+rateLimit.perUser();
+
+// IP-based rate limiting
+rateLimit.perIP();
+```
+
+### Caching Helpers
+
+```typescript
+import { cache } from '$lib/vibeskit';
+
+// Predefined TTL
+cache.short(); // 1 minute
+cache.medium(); // 5 minutes
+cache.long(); // 1 hour
+
+// Custom TTL
+cache.custom(300); // 5 minutes
+
+// Dynamic cache keys
+cache.userBased(); // Include user ID in key
+cache.projectBased(); // Include project ID in key
+```
+
+### Billing Helpers
+
+```typescript
+import { billing } from '$lib/vibeskit';
+
+// Feature access requirements
+billing.feature('premium-chat');
+
+// Credit consumption
+billing.credits('chat-messages', 1);
+billing.credits('ai-generations', 5);
+
+// Combined feature + credits
+billing.featureWithCredits('premium-chat', 'chat-messages', 1);
+```
+
+## HTTP Methods
+
+VibesKit provides wrappers for all standard HTTP methods:
+
+```typescript
+import { vibesGET, vibesPOST, vibesPUT, vibesDELETE, vibesPATCH } from '$lib/vibeskit';
+
+// GET endpoint
+export const GET = vibesGET(
+	{
+		metadata: { summary: 'List items' },
+		caching: cache.medium()
+	},
+	handler
+);
+
+// POST endpoint
+export const POST = vibesPOST(
+	{
+		metadata: { summary: 'Create item' },
+		validation: { body: createItemSchema },
+		rateLimit: rateLimit.standard()
+	},
+	handler
+);
+
+// PUT endpoint
+export const PUT = vibesPUT(
+	{
+		metadata: { summary: 'Update item' },
+		validation: {
+			params: itemParamsSchema,
+			body: updateItemSchema
+		}
+	},
+	handler
+);
+
+// DELETE endpoint
+export const DELETE = vibesDELETE(
+	{
+		metadata: { summary: 'Delete item' },
+		auth: auth.required(),
+		permissions: auth.permissions(['items:delete'])
+	},
+	handler
+);
+
+// PATCH endpoint
+export const PATCH = vibesPATCH(
+	{
+		metadata: { summary: 'Partially update item' },
+		validation: { body: patchItemSchema }
+	},
+	handler
+);
+```
+
+## Advanced Usage
+
+### Custom Rate Limiting
+
+```typescript
+export const POST = vibesPOST(
+	{
+		rateLimit: {
+			rpm: 30,
+			rph: 500,
+			key: (event) => `custom:${event.locals.user?.id || event.getClientAddress()}`
+		}
+	},
+	handler
+);
+```
+
+### Dynamic Caching
+
+```typescript
+export const GET = vibesGET(
+	{
+		caching: {
+			ttl: 600, // 10 minutes
+			key: (event) => `data:${event.params.id}:${event.url.searchParams.get('version')}`,
+			vary: ['Authorization', 'Accept-Language']
+		}
+	},
+	handler
+);
+```
+
+### Complex Permissions
+
+```typescript
+export const PUT = vibesPUT(
+	{
+		auth: auth.required(),
+		permissions: auth.permissions(['items:update:own']) // Can update own items
+		// Handler can check ownership using event.locals.requiresOwnershipCheck
+	},
+	async (event, context) => {
+		if (event.locals.requiresOwnershipCheck) {
+			// Verify user owns the item
+			const item = await getItem(event.params.id);
+			if (item.userId !== event.locals.user.id) {
+				throw error(403, 'Can only update your own items');
+			}
+		}
+
+		// Update logic here
+	}
+);
+```
+
+### Billing Integration
+
+```typescript
+import { buildUpgradeUrl } from '$lib/vibes/billing/upgrade-links';
+
+export const POST = vibesPOST(
+	{
+		billing: {
+			requiredFeatures: ['premium-api'],
+			requiredQuota: 'api-calls',
+			consumeCredits: 2,
+			recordUsage: true,
+			upgradeUrl: buildUpgradeUrl({ plan: 'plus' })
+		}
+	},
+	handler
+);
+```
+
+## Error Handling
+
+VibesKit provides structured error handling:
+
+```typescript
+// Validation errors (400)
+{
+  "message": "Invalid request body",
+  "errors": [
+    {
+      "path": ["name"],
+      "message": "String must contain at least 1 character(s)"
+    }
+  ]
+}
+
+// Rate limit errors (429)
+{
+  "error": "Rate limit exceeded",
+  "retryAfter": 60,
+  "limit": "10 requests per minute"
+}
+
+// Billing errors (402)
+{
+  "error": "subscription_required",
+  "feature": "premium-chat",
+  "currentPlan": "free",
+  "upgradeUrl": "/pricing?dialog=upgrade&plan=plus"
+}
+
+// Permission errors (403)
+{
+  "message": "Insufficient permissions"
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Redis for caching and rate limiting
+REDIS_URL=redis://localhost:6379
+
+# Rate limiting defaults
+DEFAULT_RATE_LIMIT_RPM=10
+DEFAULT_RATE_LIMIT_RPH=100
+
+# Caching defaults
+DEFAULT_CACHE_TTL=300
+CACHE_PREFIX=vibeskit
+```
+
+### Customization
+
+```typescript
+// Custom rate limiter
+import { TokenBucketRateLimiter } from '$lib/vibeskit/middleware';
+
+const customLimiter = new TokenBucketRateLimiter({
+	max: 50,
+	refillRate: 1,
+	refillInterval: 60
+});
+
+// Custom cache manager
+import { CacheManager } from '$lib/vibeskit/middleware';
+
+const customCache = new CacheManager({
+	ttl: 1800,
+	prefix: 'myapp',
+	compress: true
+});
+```
+
+## Architecture
+
+```
+vibeskit/
+├── index.ts              # Main exports
+├── wrapper.ts            # Core wrapper logic
+├── types.ts              # TypeScript definitions
+├── helpers/              # Convenience functions
+│   ├── auth.ts          # Authentication helpers
+│   ├── rate-limit.ts    # Rate limiting helpers
+│   ├── cache.ts         # Caching helpers
+│   ├── billing.ts       # Billing helpers
+│   └── validation.ts    # Validation helpers
+└── middleware/           # Core functionality
+    ├── rate-limiter.ts  # Rate limiting implementation
+    ├── cache-manager.ts # Cache management
+    └── permission-checker.ts # Permission checking
+```
+
+## Compatibility
+
+VibesKit is built on top of and fully compatible with:
+
+- **SvelteKit**: Native SvelteKit RequestHandler pattern
+- **Existing Infrastructure**: Uses existing Redis, rate limiting, and billing services
+- **Current Endpoints**: Drop-in replacement for existing endpoint wrapper
+- **OpenAPI**: Automatic API documentation generation
+- **Type Safety**: Full TypeScript support with existing schemas
+
+## Getting Started
+
+Import vibeskit and use the wrapper functions:
+
+```typescript
+import { vibesPOST } from '$lib/vibeskit';
+
+// Clean, declarative API endpoint configuration
+```
+
+## Performance
+
+VibesKit is designed for performance:
+
+- **Redis-based caching**: Sub-millisecond cache hits
+- **Efficient rate limiting**: Token bucket algorithms
+- **Minimal overhead**: Optimized request processing
+- **Connection pooling**: Shared Redis connections
+- **Smart defaults**: Reasonable configurations out of the box
+
+## Testing
+
+VibesKit includes comprehensive testing utilities:
+
+```typescript
+import { createTestHandler } from '$lib/vibeskit/testing';
+
+const testHandler = createTestHandler({
+	auth: auth.required(),
+	rateLimit: rateLimit.standard()
+});
+
+// Test with authenticated user
+await testHandler.withUser(user).post('/api/test', { data: 'test' });
+
+// Test rate limiting
+await testHandler.testRateLimit('/api/test', 11); // Should fail on 11th request
+```
+
+See the full testing documentation in `/tests/vibeskit/` for complete examples.

package/dist/lib/app-shell/plugin.d.ts

@@ -0,0 +1,2 @@
+export declare const appShellPlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+export default appShellPlugin;

package/dist/lib/app-shell/plugin.js

@@ -0,0 +1,29 @@
+/**
+ * Kit's app-shell runtime plugin: registers the `app-shell/utility` kind and
+ * the per-runtime utility host. Packages that contribute utilities list
+ * `APP_SHELL_PLUGIN_ID` in their plugin `dependencies`.
+ */
+import { createRuntimeImplementation, createRuntimePlugin, loader } from '@vibesdotdev/kernel';
+import { appShellUtilityHostContextDescriptor, appShellUtilityKind } from "../components/app-shell/app-shell-utility.kind.js";
+import { createAppShellUtilityHost } from "./utility-host.js";
+import { APP_SHELL_PLUGIN_ID, APP_SHELL_UTILITY_HOST_CONTEXT_ID } from "../components/app-shell/schemas/app-shell-utility.js";
+export const appShellPlugin = createRuntimePlugin({
+    id: APP_SHELL_PLUGIN_ID,
+    name: 'App shell',
+    description: 'Shell utilities that every Kit ProductShell renders from its runtime.',
+    kinds: [appShellUtilityKind],
+    descriptors: [appShellUtilityHostContextDescriptor],
+    loaders: [
+        // The kernel caches a resolved implementation per runtime, so each
+        // runtime gets exactly one host and no state crosses runtimes.
+        loader(APP_SHELL_UTILITY_HOST_CONTEXT_ID, { kind: 'context' }, async () => {
+            const host = createAppShellUtilityHost();
+            return createRuntimeImplementation({
+                kind: 'context',
+                id: APP_SHELL_UTILITY_HOST_CONTEXT_ID,
+                implementation: { provide: () => host }
+            });
+        })
+    ]
+});
+export default appShellPlugin;

package/dist/lib/app-shell/utility-host.d.ts

@@ -0,0 +1,3 @@
+import type { AppShellUtilityHost } from '../components/app-shell/schemas/app-shell-utility.ts';
+/** One host per runtime: mounted Kit surfaces attach; open requests go to the newest first. */
+export declare function createAppShellUtilityHost(): AppShellUtilityHost;

package/dist/lib/app-shell/utility-host.js

@@ -0,0 +1,21 @@
+/** One host per runtime: mounted Kit surfaces attach; open requests go to the newest first. */
+export function createAppShellUtilityHost() {
+    const surfaces = [];
+    return {
+        attach(surface) {
+            surfaces.push(surface);
+            return () => {
+                const index = surfaces.lastIndexOf(surface);
+                if (index !== -1)
+                    surfaces.splice(index, 1);
+            };
+        },
+        open(id) {
+            for (let index = surfaces.length - 1; index >= 0; index -= 1) {
+                if (surfaces[index]?.open(id))
+                    return true;
+            }
+            return false;
+        }
+    };
+}

package/dist/lib/app-shell/utility.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Public `app-shell/utility` contract: the descriptor schema, the props Kit
+ * hands a utility component, and `openAppShellUtility` for callers (a command
+ * palette entry, a keyboard shortcut) that open a utility programmatically.
+ */
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+import { type AppShellUtilityHost } from '../components/app-shell/schemas/app-shell-utility.ts';
+export * from '../components/app-shell/schemas/app-shell-utility.ts';
+/**
+ * The runtime's utility host, or `undefined` when the runtime does not compose
+ * Kit's app-shell plugin. Never creates a fallback host.
+ */
+export declare function resolveAppShellUtilityHost(runtime: RuntimeRef): Promise<AppShellUtilityHost | undefined>;
+/**
+ * Ask a mounted Kit surface on this runtime to open utility `id`. Resolves
+ * `true` when a surface shows that utility to its viewer and opened it, and
+ * `false` (a no-op) when visibility hides it, it is not registered, or no
+ * surface is mounted. A malformed id refuses.
+ */
+export declare function openAppShellUtility(runtime: RuntimeRef, id: string): Promise<boolean>;

package/dist/lib/app-shell/utility.js

@@ -0,0 +1,44 @@
+import { settle } from "../attempt.js";
+import { failureClass } from "../failure-class.js";
+import { kitLogger } from '../kit-logger';
+import * as z from 'zod/v4';
+import { APP_SHELL_UTILITY_HOST_CONTEXT_ID, AppShellUtilityIdSchema } from "../components/app-shell/schemas/app-shell-utility.js";
+export * from "../components/app-shell/schemas/app-shell-utility.js";
+const logger = kitLogger('vibeskit-app-shell-utility');
+const AppShellUtilityHostContractSchema = z.object({ attach: z.function(), open: z.function() });
+const AppShellUtilityHostSchema = z.custom((value) => AppShellUtilityHostContractSchema.safeParse(value).success);
+/**
+ * The runtime's utility host, or `undefined` when the runtime does not compose
+ * Kit's app-shell plugin. Never creates a fallback host.
+ */
+export async function resolveAppShellUtilityHost(runtime) {
+    if (!runtime.hasKind('context'))
+        return undefined;
+    const query = runtime.query('context').withId(APP_SHELL_UTILITY_HOST_CONTEXT_ID);
+    if (!(await query.firstDescriptorAsync()))
+        return undefined;
+    const resolved = await settle(() => query.resolve());
+    if (!resolved.ok) {
+        logger.warn('App-shell utility host could not be resolved', {
+            reason: failureClass(resolved.error)
+        });
+        return undefined;
+    }
+    const host = AppShellUtilityHostSchema.safeParse(resolved.value);
+    if (!host.success) {
+        logger.warn('App-shell utility host has the wrong shape', { reason: 'host-invalid' });
+        return undefined;
+    }
+    return host.data;
+}
+/**
+ * Ask a mounted Kit surface on this runtime to open utility `id`. Resolves
+ * `true` when a surface shows that utility to its viewer and opened it, and
+ * `false` (a no-op) when visibility hides it, it is not registered, or no
+ * surface is mounted. A malformed id refuses.
+ */
+export async function openAppShellUtility(runtime, id) {
+    const utilityId = AppShellUtilityIdSchema.parse(id);
+    const host = await resolveAppShellUtilityHost(runtime);
+    return host ? host.open(utilityId) : false;
+}