@vibesdotdev/storage 0.0.1

package/src/manifest/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Storage Manifest Module
+ *
+ * Provides the StorageManifest base class for working with stored data.
+ */
+
+export { StorageManifest } from './base';

package/src/manifest/source-policy.ts

@@ -0,0 +1,74 @@
+import type { StorageScope } from '../schemas/manifest-descriptor.ts';
+
+export type ManifestDataSource = 'user-localdb' | 'project-file' | 'cloud-api';
+
+export const MANIFEST_SOURCE_PRECEDENCE: ManifestDataSource[] = [
+	'cloud-api',
+	'project-file',
+	'user-localdb'
+];
+
+const SOURCE_ADAPTER_CANDIDATES: Record<ManifestDataSource, string[]> = {
+	// `storage.memory` is included as the last-resort candidate for every
+	// source so tests can exercise source-policy code paths without
+	// spinning up a real localdb / drizzle / json file. Production
+	// descriptors don't list `storage.memory` in `allowedAdapters`, so
+	// this only kicks in when a descriptor explicitly opts in (test-only).
+	'cloud-api': ['storage.cloud-api', 'storage.drizzle', 'storage.memory'],
+	'project-file': ['storage.json', 'storage.memory'],
+	'user-localdb': ['storage.localdb', 'storage.memory']
+};
+
+const ADAPTER_SOURCE_CANDIDATES: Record<string, ManifestDataSource[]> = {
+	'storage.cloud-api': ['cloud-api'],
+	'storage.drizzle': ['cloud-api'],
+	'storage.json': ['project-file'],
+	'storage.localdb': ['user-localdb'],
+	// `storage.memory` resolves back to `user-localdb` for round-trips —
+	// callers asking "which source does this adapter belong to?" get a
+	// sensible default. In practice memory adapters are test-only and
+	// the round-trip rarely matters.
+	'storage.memory': ['user-localdb']
+};
+
+export function resolveAdapterForSource(
+	source: ManifestDataSource,
+	allowedAdapters: string[]
+): string | null {
+	const allowed = new Set(allowedAdapters);
+	for (const adapterId of SOURCE_ADAPTER_CANDIDATES[source]) {
+		if (allowed.has(adapterId)) return adapterId;
+	}
+	return null;
+}
+
+export function resolveScopeForSource(
+	source: ManifestDataSource,
+	fallbackScope: StorageScope = 'global'
+): StorageScope {
+	if (source === 'project-file') return 'project';
+	if (source === 'user-localdb') {
+		return fallbackScope === 'project' || fallbackScope === 'local' ? fallbackScope : 'global';
+	}
+	return 'global';
+}
+
+export function resolveAdapterOrderBySource(allowedAdapters: string[]): string[] {
+	const ordered: string[] = [];
+	for (const source of MANIFEST_SOURCE_PRECEDENCE) {
+		for (const adapterId of SOURCE_ADAPTER_CANDIDATES[source]) {
+			if (allowedAdapters.includes(adapterId) && !ordered.includes(adapterId)) {
+				ordered.push(adapterId);
+			}
+		}
+	}
+	for (const adapterId of allowedAdapters) {
+		if (!ordered.includes(adapterId)) ordered.push(adapterId);
+	}
+	return ordered;
+}
+
+export function resolveSourceFromAdapter(adapterId: string): ManifestDataSource | null {
+	const candidates = ADAPTER_SOURCE_CANDIDATES[adapterId];
+	return candidates?.[0] ?? null;
+}

package/src/paths.ts

@@ -0,0 +1,171 @@
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+
+const WINDOWS_DRIVE_PATTERN = /^[A-Za-z]:/;
+const WINDOWS_DRIVE_ABSOLUTE_PATTERN = /^[A-Za-z]:[\\/]/;
+
+function readEnv(name: string): string | undefined {
+	if (typeof process === 'undefined') return undefined;
+	const envSource = process['env'] as Record<string, string | undefined> | undefined;
+	return envSource?.[name];
+}
+
+function readWorkingDirectory(): string | undefined {
+	const fromEnv = readEnv('PWD') ?? readEnv('INIT_CWD');
+	if (fromEnv && fromEnv.trim().length > 0) return fromEnv;
+	if (typeof process === 'undefined') return undefined;
+	if (typeof process.cwd !== 'function') return undefined;
+	try {
+		return process.cwd();
+	} catch {
+		return undefined;
+	}
+}
+
+function toSlashSeparators(path: string): string {
+	return path.replaceAll('\\', '/');
+}
+
+function isAbsolutePath(path: string): boolean {
+	const normalized = toSlashSeparators(path);
+	return (
+		normalized.startsWith('/') ||
+		normalized.startsWith('//') ||
+		WINDOWS_DRIVE_ABSOLUTE_PATTERN.test(path)
+	);
+}
+
+function normalizePath(path: string): string {
+	const normalized = toSlashSeparators(path);
+
+	let prefix = '';
+	let absolute = false;
+	let rest = normalized;
+
+	if (normalized.startsWith('//')) {
+		absolute = true;
+		rest = normalized.slice(2);
+		const segments = rest.split('/').filter((segment) => segment.length > 0);
+		if (segments.length >= 2) {
+			prefix = `//${segments.shift()}/${segments.shift()}`;
+			rest = segments.join('/');
+		} else {
+			prefix = '//';
+			rest = segments.join('/');
+		}
+	} else if (WINDOWS_DRIVE_PATTERN.test(normalized)) {
+		prefix = normalized.slice(0, 2).toUpperCase();
+		rest = normalized.slice(2);
+		absolute = rest.startsWith('/');
+	} else if (normalized.startsWith('/')) {
+		absolute = true;
+		rest = normalized.slice(1);
+	}
+
+	const rawSegments = rest.split('/');
+	const segments: string[] = [];
+	for (const segment of rawSegments) {
+		if (segment.length === 0 || segment === '.') continue;
+		if (segment === '..') {
+			if (segments.length > 0 && segments[segments.length - 1] !== '..') {
+				segments.pop();
+				continue;
+			}
+			if (!absolute) segments.push('..');
+			continue;
+		}
+		segments.push(segment);
+	}
+
+	if (prefix.startsWith('//')) {
+		return segments.length > 0 ? `${prefix}/${segments.join('/')}` : prefix;
+	}
+
+	if (WINDOWS_DRIVE_PATTERN.test(prefix)) {
+		if (!absolute) {
+			return segments.length > 0 ? `${prefix}/${segments.join('/')}` : prefix;
+		}
+		return segments.length > 0 ? `${prefix}/${segments.join('/')}` : `${prefix}/`;
+	}
+
+	if (absolute) {
+		return segments.length > 0 ? `/${segments.join('/')}` : '/';
+	}
+
+	return segments.length > 0 ? segments.join('/') : '.';
+}
+
+function normalizeAbsolutePath(path: string | undefined): string | undefined {
+	if (!path) return undefined;
+	const trimmed = path.trim();
+	if (trimmed.length === 0) return undefined;
+
+	const cwd = readWorkingDirectory();
+	const absolutePath = isAbsolutePath(trimmed) ? trimmed : cwd ? `${cwd}/${trimmed}` : undefined;
+	if (!absolutePath) return undefined;
+
+	const normalized = normalizePath(absolutePath);
+	return isAbsolutePath(normalized) ? normalized : undefined;
+}
+
+function isRootPath(path: string): boolean {
+	const normalized = normalizePath(path);
+	return (
+		normalized === '/' || /^[A-Za-z]:\/$/.test(normalized) || /^\/\/[^/]+\/[^/]+$/.test(normalized)
+	);
+}
+
+export function resolveHomePath(): string {
+	return (
+		normalizeAbsolutePath(readEnv('HOME')) ??
+		normalizeAbsolutePath(readEnv('USERPROFILE')) ??
+		normalizeAbsolutePath(readEnv('TMPDIR')) ??
+		normalizeAbsolutePath(readEnv('TEMP')) ??
+		normalizeAbsolutePath(readEnv('TMP')) ??
+		normalizeAbsolutePath(readWorkingDirectory()) ??
+		'.'
+	);
+}
+
+function readContextWorkspacePath(
+	context: KindContext | Record<string, unknown> | undefined
+): string | undefined {
+	if (!context) return undefined;
+	const value = context['runtime/workspace-path'];
+	return typeof value === 'string' ? value : undefined;
+}
+
+export function resolveWorkspacePath(
+	context?: KindContext | Record<string, unknown>,
+	preferredWorkspacePath?: string
+): string {
+	const candidates = [
+		preferredWorkspacePath,
+		readContextWorkspacePath(context),
+		readEnv('VIBES_WORKSPACE_PATH'),
+		readEnv('PWD'),
+		readEnv('INIT_CWD')
+	];
+
+	for (const candidate of candidates) {
+		const normalized = normalizeAbsolutePath(candidate);
+		if (!normalized) continue;
+		if (isRootPath(normalized)) continue;
+		return normalized;
+	}
+
+	return resolveHomePath();
+}
+
+export function resolveScopePathTemplate(pathTemplate: string, workspacePath: string): string {
+	const homePath = resolveHomePath();
+	const profile = readEnv('VIBES_PROFILE') || readEnv('VIBES_PROFILE_NAME') || '';
+	return pathTemplate
+		.replaceAll('{home}', homePath)
+		.replaceAll('{cwd}', workspacePath)
+		.replaceAll('{workspace}', workspacePath)
+		.replaceAll('{profile}', profile);
+}
+
+export function resolveAtlasDbPath(projectId: string, workspacePath: string): string {
+	return normalizePath(`${workspacePath}/.vibes/atlas/${projectId}.db`);
+}

package/src/policy/context.ts

@@ -0,0 +1,30 @@
+import { getRuntimeEnv } from '@vibesdotdev/runtime';
+import { StoragePersistenceModeSchema } from './persistence';
+import { StoragePolicyContextSchema, type StoragePolicyContextValue } from './overrides';
+
+/**
+ * Load storage policy context with environment variable overrides.
+ *
+ * Returns the default storage policy, optionally overridden by environment
+ * variables VIBES_STORAGE_MODE and VIBES_STORAGE_DEFAULT_ADAPTER.
+ */
+export async function loadStoragePolicyContext(): Promise<StoragePolicyContextValue> {
+	const defaultPolicy = StoragePolicyContextSchema.parse({});
+	return applyEnvOverrides(defaultPolicy);
+}
+
+function applyEnvOverrides(policy: StoragePolicyContextValue): StoragePolicyContextValue {
+	const mode = getRuntimeEnv('VIBES_STORAGE_MODE');
+	const defaultAdapter = getRuntimeEnv('VIBES_STORAGE_DEFAULT_ADAPTER');
+	if (!mode && !defaultAdapter) return policy;
+
+	const parsedMode = mode ? StoragePersistenceModeSchema.safeParse(mode) : null;
+	return {
+		...policy,
+		default: {
+			...(policy.default ?? {}),
+			...(parsedMode?.success ? { mode: parsedMode.data } : {}),
+			...(defaultAdapter ? { defaultAdapter } : {})
+		}
+	};
+}

package/src/policy/index.ts

@@ -0,0 +1,20 @@
+export {
+	StoragePersistenceModeSchema,
+	StoragePersistencePolicySchema,
+	resolveStoragePolicy,
+	isRemoteStorageAdapter,
+	type StoragePersistenceMode,
+	type StoragePersistencePolicy,
+	type StoragePolicyDescriptorDefaults,
+	type StoragePolicyOverrides,
+	type ResolvedStoragePolicy
+} from './persistence';
+
+export {
+	StoragePolicyContextSchema,
+	StoragePolicyOverrideSchema,
+	resolveStoragePolicyOverridesFromContext,
+	type StoragePolicyContextValue
+} from './overrides';
+
+export { loadStoragePolicyContext } from './context';

package/src/policy/overrides.ts

@@ -0,0 +1,46 @@
+import * as z from 'zod/v4';
+import { StoragePersistenceModeSchema, type StoragePolicyOverrides } from './persistence';
+
+export const StoragePolicyOverrideSchema = z.object({
+	mode: StoragePersistenceModeSchema.optional(),
+	defaultAdapter: z.string().optional(),
+	localAdapters: z.array(z.string()).optional(),
+	remoteAdapters: z.array(z.string()).optional()
+});
+
+export const StoragePolicyContextSchema = z.object({
+	default: StoragePolicyOverrideSchema.optional(),
+	records: z.record(z.string(), StoragePolicyOverrideSchema).default({})
+});
+
+export type StoragePolicyContextValue = z.infer<typeof StoragePolicyContextSchema>;
+
+export function resolveStoragePolicyOverridesFromContext(
+	policy: unknown,
+	recordId: string
+): StoragePolicyOverrides | undefined {
+	const parsed = StoragePolicyContextSchema.safeParse(policy);
+	if (!parsed.success) return undefined;
+
+	const base = parsed.data.default ?? {};
+	const record = parsed.data.records[recordId] ?? {};
+	const mode = record.mode ?? base.mode;
+	const localAdapters = record.localAdapters ?? base.localAdapters;
+	const remoteAdapters = record.remoteAdapters ?? base.remoteAdapters;
+	const defaultAdapter = record.defaultAdapter ?? base.defaultAdapter;
+
+	const persistence =
+		mode || localAdapters || remoteAdapters
+			? {
+					...(mode ? { mode } : {}),
+					...(localAdapters ? { localAdapters } : {}),
+					...(remoteAdapters ? { remoteAdapters } : {})
+				}
+			: undefined;
+
+	if (!persistence && !defaultAdapter) return undefined;
+	return {
+		...(persistence ? { persistence } : {}),
+		...(defaultAdapter ? { defaultAdapter } : {})
+	};
+}

package/src/policy/persistence.ts

@@ -0,0 +1,117 @@
+import * as z from 'zod/v4';
+
+export const StoragePersistenceModeSchema = z.enum([
+	'local-only',
+	'local-first',
+	'remote-first',
+	'remote-only'
+]);
+
+export const StoragePersistencePolicySchema = z.object({
+	mode: StoragePersistenceModeSchema.default('local-first'),
+	localAdapters: z.array(z.string()).optional(),
+	remoteAdapters: z.array(z.string()).optional()
+});
+
+export type StoragePersistenceMode = z.infer<typeof StoragePersistenceModeSchema>;
+export type StoragePersistencePolicy = z.infer<typeof StoragePersistencePolicySchema>;
+
+export interface StoragePolicyDescriptorDefaults {
+	allowedAdapters: string[];
+	defaultAdapter?: string;
+	persistence?: StoragePersistencePolicy;
+}
+
+export interface StoragePolicyOverrides {
+	persistence?: Partial<StoragePersistencePolicy>;
+	defaultAdapter?: string;
+}
+
+export interface ResolvedStoragePolicy {
+	mode: StoragePersistenceMode;
+	defaultAdapter: string | null;
+	adapterOrder: string[];
+	localAdapters: string[];
+	remoteAdapters: string[];
+}
+
+const REMOTE_STORAGE_ADAPTERS = new Set(['storage.cloud-api', 'storage.drizzle']);
+
+export function resolveStoragePolicy(
+	descriptor: StoragePolicyDescriptorDefaults,
+	overrides?: StoragePolicyOverrides
+): ResolvedStoragePolicy {
+	const base = descriptor.persistence ?? { mode: 'local-first' };
+	const persistence = StoragePersistencePolicySchema.parse({
+		...base,
+		...overrides?.persistence
+	});
+	const allowedAdapters = unique(descriptor.allowedAdapters);
+	const localAdapters = unique(
+		persistence.localAdapters ??
+			allowedAdapters.filter((adapterId) => !isRemoteStorageAdapter(adapterId))
+	).filter((adapterId) => allowedAdapters.includes(adapterId));
+	const remoteAdapters = unique(
+		persistence.remoteAdapters ??
+			allowedAdapters.filter((adapterId) => isRemoteStorageAdapter(adapterId))
+	).filter((adapterId) => allowedAdapters.includes(adapterId));
+	const orderedByMode = orderAdaptersByMode(persistence.mode, localAdapters, remoteAdapters);
+	const defaultAdapter = resolveDefaultAdapter(
+		overrides?.defaultAdapter ?? descriptor.defaultAdapter ?? null,
+		allowedAdapters,
+		orderedByMode
+	);
+
+	return {
+		mode: persistence.mode,
+		defaultAdapter,
+		adapterOrder: defaultAdapter ? prioritize(defaultAdapter, orderedByMode) : orderedByMode,
+		localAdapters,
+		remoteAdapters
+	};
+}
+
+export function isRemoteStorageAdapter(adapterId: string): boolean {
+	return REMOTE_STORAGE_ADAPTERS.has(adapterId);
+}
+
+function orderAdaptersByMode(
+	mode: StoragePersistenceMode,
+	localAdapters: string[],
+	remoteAdapters: string[]
+): string[] {
+	switch (mode) {
+		case 'local-only':
+			return [...localAdapters];
+		case 'remote-only':
+			return [...remoteAdapters];
+		case 'remote-first':
+			return [...remoteAdapters, ...localAdapters];
+		case 'local-first':
+		default:
+			return [...localAdapters, ...remoteAdapters];
+	}
+}
+
+function resolveDefaultAdapter(
+	defaultAdapter: string | null,
+	allowedAdapters: string[],
+	orderedByMode: string[]
+): string | null {
+	if (
+		defaultAdapter &&
+		allowedAdapters.includes(defaultAdapter) &&
+		orderedByMode.includes(defaultAdapter)
+	) {
+		return defaultAdapter;
+	}
+	return orderedByMode[0] ?? null;
+}
+
+function prioritize(adapterId: string, orderedAdapters: string[]): string[] {
+	return [adapterId, ...orderedAdapters.filter((candidate) => candidate !== adapterId)];
+}
+
+function unique(values: string[]): string[] {
+	return [...new Set(values)];
+}

package/src/policy/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Storage Policy Types
+ *
+ * Defines the types and interfaces for storage policy resolution and overrides.
+ */
+
+export interface StoragePolicy {
+  mode: "persistent" | "ephemeral" | "cached";
+  adapter: string;
+  namespace: string;
+  ttl?: number;
+  compression?: boolean;
+  encryption?: boolean;
+}
+
+export interface StoragePolicyOverride {
+  [key: string]: unknown;
+}
+
+export interface StoragePolicyContext {
+  resolveStoragePolicy: (
+    namespace: string,
+    options?: Record<string, unknown>,
+  ) => Promise<StoragePolicy>;
+  resolveStoragePolicyOverrides: (
+    context: Record<string, unknown>,
+  ) => Promise<StoragePolicyOverride>;
+}