mdcontext 0.0.1 → 0.2.0

package/research/config-analysis/02-strategy-recommendation.md

@@ -0,0 +1,428 @@
+# Configuration and CLI Strategy Recommendation for mdcontext
+
+## Executive Summary
+
+This document synthesizes research from two approaches to CLI and configuration management for the mdcontext project:
+
+1. **Traditional Stack**: c12/citty/Zod (UnJS ecosystem)
+2. **Effect Stack**: @effect/cli, Effect Config, Layers
+
+**Recommendation**: Adopt the **Effect ecosystem** for CLI and configuration management, contingent on a broader commitment to Effect as the application's foundational paradigm. If Effect adoption is uncertain or limited, the **c12/citty/Zod stack** provides a pragmatic, lower-risk alternative.
+
+---
+
+## Decision Matrix
+
+| Criterion                     | Weight | c12/citty/Zod | Effect Ecosystem | Notes                                    |
+| ----------------------------- | ------ | ------------- | ---------------- | ---------------------------------------- |
+| **Learning Curve**            | 15%    | 9/10          | 5/10             | Effect requires paradigm shift           |
+| **Team Adoption**             | 15%    | 8/10          | 5/10             | UnJS is more approachable                |
+| **Type Safety**               | 20%    | 7/10          | 10/10            | Effect provides exhaustive type tracking |
+| **Developer Experience**      | 15%    | 8/10          | 8/10             | Both excellent once learned              |
+| **Testing Patterns**          | 10%    | 6/10          | 9/10             | Effect Layers excel at DI/mocking        |
+| **Migration Complexity**      | 10%    | 8/10          | 4/10             | Effect requires significant rewrite      |
+| **Long-term Maintainability** | 10%    | 7/10          | 9/10             | Effect's structure scales better         |
+| **Ecosystem Momentum**        | 5%     | 8/10          | 7/10             | Both growing; UnJS more mature           |
+| **Weighted Score**            | 100%   | **7.5/10**    | **7.3/10**       | Slight edge to traditional               |
+
+The scores are close, indicating this is a strategic choice rather than a clear technical winner.
+
+---
+
+## Detailed Comparison
+
+### 1. Learning Curve and Team Adoption
+
+#### c12/citty/Zod Stack
+
+- **Time to productivity**: 1-2 days
+- **Prerequisite knowledge**: Basic TypeScript, familiar async/await patterns
+- **Documentation quality**: Excellent, extensive UnJS ecosystem docs
+- **Community resources**: Many examples from Nuxt, Nitro, and other UnJS projects
+
+#### Effect Ecosystem
+
+- **Time to productivity**: 1-2 weeks for basic patterns, months for mastery
+- **Prerequisite knowledge**: Functional programming concepts, Effect core (generators, services, layers)
+- **Documentation quality**: Good and improving; steeper initial ramp
+- **Community resources**: Growing Discord community, Effect.website docs
+
+**Verdict**: c12/citty/Zod is significantly easier for onboarding new contributors. Effect requires commitment to learning a new paradigm but pays dividends for complex applications.
+
+---
+
+### 2. Type Safety and Developer Experience
+
+#### c12/citty/Zod Stack
+
+```typescript
+// Good type safety with Zod inference
+const ConfigSchema = z.object({
+  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
+  port: z.coerce.number().default(3000),
+});
+
+type Config = z.infer<typeof ConfigSchema>; // Fully typed
+
+// defineConfig provides IDE autocomplete
+export default defineConfig({
+  logLevel: "debug", // Autocomplete works
+});
+```
+
+- Types are inferred from Zod schemas
+- `defineConfig` pattern provides excellent IDE support
+- Runtime validation catches configuration errors
+- Error messages from Zod are clear and actionable
+
+#### Effect Ecosystem
+
+```typescript
+// Superior type tracking through Effect types
+const program = Effect.gen(function* () {
+  const port = yield* Config.number("PORT"); // Effect<number, ConfigError>
+  const host = yield* Config.string("HOST"); // Effect<string, ConfigError>
+  return { host, port };
+}); // Effect<{host: string, port: number}, ConfigError>
+
+// Errors are tracked in the type system
+// Dependencies are tracked through R (Requirements) type
+```
+
+- Full effect tracking: success type, error type, and requirements
+- ConfigError types distinguish missing vs. invalid configuration
+- Layer dependencies are compile-time verified
+- Exhaustive pattern matching on errors
+
+**Verdict**: Effect provides superior type safety by tracking errors and dependencies in the type system. Zod provides "good enough" type safety for most use cases with less cognitive overhead.
+
+---
+
+### 3. Testing Patterns
+
+#### c12/citty/Zod Stack
+
+```typescript
+// Testing requires manual mocking
+import { vi } from "vitest";
+import { loadConfig } from "c12";
+
+vi.mock("c12", () => ({
+  loadConfig: vi.fn().mockResolvedValue({
+    config: { logLevel: "debug", port: 3000 },
+    configFile: "/mock/path",
+  }),
+}));
+
+// Tests need to manage mock state
+afterEach(() => {
+  vi.clearAllMocks();
+});
+```
+
+- Standard vitest/jest mocking patterns
+- Environment variables need process.env manipulation
+- Test isolation requires careful mock management
+- No built-in pattern for dependency injection
+
+#### Effect Ecosystem
+
+```typescript
+// Testing with Layer replacement
+const TestConfigProvider = Layer.setConfigProvider(
+  ConfigProvider.fromMap(
+    new Map([
+      ["LOG_LEVEL", "debug"],
+      ["PORT", "3000"],
+    ]),
+  ),
+);
+
+const TestAppConfig = Layer.succeed(AppConfig, {
+  logLevel: "debug",
+  port: 3000,
+});
+
+// Test with injected dependencies
+const result = await Effect.runPromise(
+  program.pipe(Effect.provide(TestAppConfig)),
+);
+```
+
+- Layer system enables clean dependency injection
+- Test layers can be composed and reused
+- No global mock pollution
+- Built-in support for mocking at service boundaries
+
+**Verdict**: Effect's Layer system provides superior testing ergonomics, especially for integration tests and complex service graphs. The c12 approach works but requires more boilerplate.
+
+---
+
+### 4. Migration Complexity from Current State
+
+#### To c12/citty/Zod
+
+Migration steps:
+
+1. Add c12 and Zod dependencies
+2. Define Zod schema for configuration
+3. Create `defineConfig` helper
+4. Replace current config loading with c12
+5. Add citty for CLI if not using another solution
+
+**Estimated effort**: 1-2 days for basic implementation
+**Risk level**: Low - incremental migration possible
+
+#### To Effect Ecosystem
+
+Migration steps:
+
+1. Add Effect core and platform packages
+2. Learn Effect fundamentals (generators, Effects, services)
+3. Rewrite configuration as ConfigProvider/Layer pattern
+4. Migrate CLI to @effect/cli
+5. Refactor dependent code to consume Effect services
+6. Update error handling throughout
+
+**Estimated effort**: 1-2 weeks minimum, ongoing learning
+**Risk level**: High - requires comprehensive rewrite
+
+**Verdict**: c12/citty/Zod allows incremental adoption. Effect is an all-or-nothing paradigm shift.
+
+---
+
+### 5. Long-term Maintainability
+
+#### c12/citty/Zod Stack
+
+- **Pros**:
+  - Familiar patterns for most TypeScript developers
+  - Easy to onboard new team members
+  - Smaller dependency footprint
+  - UnJS ecosystem is stable and production-proven (Nuxt, Nitro)
+
+- **Cons**:
+  - Error handling remains ad-hoc (try/catch)
+  - Dependency injection must be implemented manually
+  - Configuration precedence logic can become complex
+  - Less structured approach to service composition
+
+#### Effect Ecosystem
+
+- **Pros**:
+  - Enforced structure through type system
+  - Error handling is explicit and composable
+  - Resource management via Scope prevents leaks
+  - Service dependencies are compile-time verified
+  - Excellent for large, complex applications
+
+- **Cons**:
+  - Requires ongoing Effect expertise
+  - Fewer developers familiar with paradigm
+  - Bundle size considerations
+  - Breaking changes possible as Effect evolves (though now stable)
+
+**Verdict**: Effect provides stronger architectural guarantees for long-term maintenance but requires sustained investment in the paradigm.
+
+---
+
+### 6. Ecosystem Momentum
+
+#### c12/citty/Zod (UnJS)
+
+- **Adoption**: Nuxt (100k+ GitHub stars), Nitro, many production deployments
+- **Maintenance**: UnJS is actively maintained by Nuxt team
+- **Growth**: Stable, mature ecosystem
+- **Industry trend**: TypeScript config files (`defineConfig`) are the 2026 standard
+
+#### Effect Ecosystem
+
+- **Adoption**: Growing rapidly in TypeScript community
+- **Maintenance**: Effect Solutions (commercial entity) supports development
+- **Growth**: Accelerating; VS Code extension, create-effect-app, growing Discord
+- **Industry trend**: Functional Effect systems gaining traction (Scala ZIO, etc.)
+
+**Verdict**: UnJS is more established; Effect is growing faster from a smaller base. Both are viable long-term.
+
+---
+
+## Recommendation
+
+### Primary Recommendation: Effect Ecosystem
+
+**Adopt Effect** if the following conditions are met:
+
+1. **mdcontext is committed to Effect** for its core functionality (not just CLI/config)
+2. **Team is willing to invest** in learning the Effect paradigm (1-2 weeks ramp-up)
+3. **Application complexity warrants it** (multiple services, complex error handling, resource management)
+
+**Rationale**:
+
+- Unified paradigm from CLI to core logic to file operations
+- Superior long-term maintainability through type-enforced architecture
+- Testing is cleaner with Layer-based dependency injection
+- The Effect ecosystem provides @effect/platform for file operations that mdcontext will need
+- Effect's ConfigProvider + Config module handles the precedence hierarchy elegantly
+
+### Fallback Recommendation: c12/citty/Zod Stack
+
+**Adopt the traditional stack** if:
+
+1. **Effect adoption is uncertain** or limited to specific modules
+2. **Rapid iteration is priority** over architectural purity
+3. **Contributor accessibility** is important (open source considerations)
+4. **Bundle size matters** for distribution
+
+**Rationale**:
+
+- Faster time to implementation
+- Lower barrier for contributors
+- Production-proven in the UnJS ecosystem
+- Allows Effect to be adopted incrementally for core logic only
+
+---
+
+## Implementation Roadmap
+
+### If Choosing Effect
+
+**Phase 1: Foundation (Week 1)**
+
+```
+- Set up @effect/cli for basic command structure
+- Implement Config service with Layer
+- Create basic commands (init, build, watch)
+- Set up test infrastructure with Layer mocking
+```
+
+**Phase 2: Integration (Week 2)**
+
+```
+- Add @effect/platform for file system operations
+- Implement configuration file support (mdcontext.config.ts)
+- Add environment variable precedence
+- Build out service layer for core functionality
+```
+
+**Phase 3: Polish (Week 3+)**
+
+```
+- Add shell completion generation
+- Implement wizard mode for complex commands
+- Add comprehensive error handling with ConfigError
+- Performance optimization
+```
+
+### If Choosing c12/citty/Zod
+
+**Phase 1: Config System (Day 1-2)**
+
+```
+- Define Zod schema for configuration
+- Set up c12 loader with defineConfig helper
+- Implement precedence: CLI > env > file > defaults
+- Create configuration module with proper types
+```
+
+**Phase 2: CLI Implementation (Day 3-4)**
+
+```
+- Set up citty with command structure
+- Integrate configuration loading
+- Add help and version commands
+- Implement core commands
+```
+
+**Phase 3: Integration (Day 5+)**
+
+```
+- Add watch mode with file system integration
+- Implement error handling patterns
+- Add testing infrastructure
+- Documentation
+```
+
+---
+
+## Appendix: Key Code Patterns
+
+### Effect Pattern: Config Service Layer
+
+```typescript
+import { Context, Effect, Layer, Config } from "effect";
+
+class AppConfig extends Context.Tag("AppConfig")<
+  AppConfig,
+  {
+    readonly logLevel: "debug" | "info" | "warn" | "error";
+    readonly port: number;
+    readonly apiKey: string | undefined;
+  }
+>() {}
+
+const AppConfigLive = Layer.effect(
+  AppConfig,
+  Effect.gen(function* () {
+    const logLevel = yield* Config.literal("LOG_LEVEL")(
+      "debug",
+      "info",
+      "warn",
+      "error",
+    ).pipe(Config.withDefault("info"));
+    const port = yield* Config.number("PORT").pipe(Config.withDefault(3000));
+    const apiKey = yield* Config.string("API_KEY").pipe(Config.optional);
+    return {
+      logLevel,
+      port,
+      apiKey: apiKey._tag === "Some" ? apiKey.value : undefined,
+    };
+  }),
+);
+```
+
+### c12/Zod Pattern: Config Loader
+
+```typescript
+import { loadConfig } from "c12";
+import { z } from "zod";
+
+const ConfigSchema = z.object({
+  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
+  port: z.coerce.number().default(3000),
+  apiKey: z.string().optional(),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+export async function loadMdcontextConfig(overrides?: Partial<Config>) {
+  const { config } = await loadConfig({
+    name: "mdcontext",
+    defaults: ConfigSchema.parse({}),
+    overrides,
+    dotenv: true,
+    globalRc: true,
+  });
+  return ConfigSchema.parse(config);
+}
+```
+
+---
+
+## References
+
+### Source Documents
+
+- `/Users/alphab/Dev/LLM/DEV/mdcontext/docs/033-research-configuration-management.md`
+- `/Users/alphab/Dev/LLM/DEV/mdcontext/docs/034-research-effect-cli-config.md`
+
+### Key Libraries
+
+- [c12 - Smart Configuration Loader](https://github.com/unjs/c12)
+- [citty - CLI Builder](https://github.com/unjs/citty)
+- [Zod - Schema Validation](https://zod.dev/)
+- [@effect/cli](https://github.com/Effect-TS/effect/tree/main/packages/cli)
+- [Effect Configuration](https://effect.website/docs/configuration/)
+
+---
+
+_Analysis completed: 2026-01-21_