@claudiv/vite-sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,20 +1,10 @@
 # @claudiv/vite-sdk
 
-> Vite plugin for Claudiv integration - Add CDML generation with HMR to your Vite projects
-
-[![npm version](https://img.shields.io/npm/v/@claudiv/vite-sdk.svg)](https://www.npmjs.com/package/@claudiv/vite-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+> Vite framework SDK for the Claudiv declarative AI interaction platform
 
 ## Overview
 
-**@claudiv/vite-sdk** brings Claudiv's declarative generation capabilities to Vite projects with seamless Hot Module Replacement (HMR) integration.
-
-**Features:**
-- 🔥 **Hot Module Replacement** - Changes to .cdml files trigger instant reloads
-- 📁 **Automatic File Watching** - Watches `claudiv/**/*.cdml` by default
-- ⚡ **Vite-Optimized** - Leverages Vite's fast build pipeline
-- 🔄 **Auto-Regeneration** - Code regenerates on .cdml file changes
-- 🎯 **Type-Safe** - Full TypeScript support
+@claudiv/vite-sdk integrates Claudiv into Vite projects as an add-on package. It provides `claudiv:*` npm scripts for initializing, watching, and generating from `.cdml` files.
 
 ## Installation
 
@@ -22,416 +12,62 @@
 npm install --save-dev @claudiv/vite-sdk
 ```
 
-**Peer Dependencies:**
-- `vite` ^6.0.0
-
-## Quick Start
-
-### 1. Add Plugin to Vite Config
+On install, `claudiv:init` script is added to your `package.json`.
 
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import { claudiv } from '@claudiv/vite-sdk';
-
-export default defineConfig({
-  plugins: [
-    claudiv({
-      specFile: 'claudiv/app.cdml',
-      outputDir: 'src/generated'
-    })
-  ]
-});
-```
+## npm Scripts
 
-### 2. Create CDML File
+After `npm run claudiv:init`, these scripts are available:
 
 ```bash
-mkdir claudiv
+npm run claudiv:init        # Scan project, generate .cdml + context
+npm run claudiv:dev         # Watch .cdml files, diff and process
+npm run claudiv:gen         # One-shot generation
+npm run claudiv:mode        # Switch between cli/api mode
 ```
 
-```xml
-<!-- claudiv/app.cdml -->
-<app target="html">
-  <dashboard gen>
-    Create an analytics dashboard with charts and stats
-  </dashboard>
-</app>
-```
+## How It Works
 
-### 3. Run Vite
+### Init
+1. Detects Vite project (vite.config.* or vite in package.json)
+2. Scans source directories (src/, lib/, app/, etc.)
+3. Generates component `.cdml` skeleton
+4. Generates `.claudiv/context.cdml` with scope-to-file mappings
+5. Generates `claudiv.project.cdml` manifest
+6. Adds remaining `claudiv:*` scripts to package.json
 
-```bash
-npm run dev
-```
+### Dev Mode
+Watches `*.cdml` files with chokidar. On change:
+1. Diffs against cached state
+2. Processes changes through context engine
+3. Executes headless Claude for each changed scope
 
-Changes to `claudiv/app.cdml` will automatically regenerate code and trigger HMR!
+### Gen Mode
+One-shot processing. Supports `--scope` filter and `--dry-run`.
 
-## Configuration
+## SDK Interface
 
-### Plugin Options
+Implements `ClaudivSDK` from `@claudiv/core`:
 
 ```typescript
-interface ClaudivPluginOptions {
-  /**
-   * Path to main CDML spec file
-   * @default 'claudiv/app.cdml'
-   */
-  specFile?: string;
-
-  /**
-   * Directory for generated code output
-   * @default 'src/generated'
-   */
-  outputDir?: string;
-
-  /**
-   * Generation mode
-   * - 'cli': Use Claude Code CLI (requires subscription)
-   * - 'api': Use Anthropic API (pay-per-use)
-   * @default 'cli'
-   */
-  mode?: 'cli' | 'api';
-
-  /**
-   * Default target language
-   * @default 'html'
-   */
-  target?: 'html' | 'react' | 'vue' | 'python' | 'bash';
-
-  /**
-   * Enable/disable file watching
-   * @default true
-   */
-  watch?: boolean;
+interface ClaudivSDK {
+  name: string;
+  frameworkDetector: FrameworkDetector;
+  init(projectRoot: string): Promise<InitResult>;
+  dev(projectRoot: string, opts: DevOptions): Promise<void>;
+  gen(projectRoot: string, opts: GenOptions): Promise<void>;
+  getScripts(): Record<string, string>;
 }
 ```
 
-### Full Example
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import { claudiv } from '@claudiv/vite-sdk';
-
-export default defineConfig({
-  plugins: [
-    claudiv({
-      specFile: 'claudiv/app.cdml',
-      outputDir: 'src/generated',
-      mode: 'api',      // Use Anthropic API
-      target: 'react',  // Generate React components
-      watch: true       // Enable HMR (default)
-    })
-  ]
-});
-```
-
-## Project Structure
-
-### Recommended Folder Layout
-
-```
-my-vite-app/
-├── claudiv/               # CDML source files (version controlled)
-│   ├── app.cdml          # Main spec
-│   ├── components/       # Component specs
-│   │   ├── header.cdml
-│   │   └── footer.cdml
-│   └── pages/            # Page specs
-│       ├── home.cdml
-│       └── about.cdml
-│
-├── src/
-│   ├── generated/        # Generated code (gitignored)
-│   │   ├── app.html
-│   │   └── components/
-│   └── main.ts           # Your entry point
-│
-├── .gitignore            # Ignore src/generated/
-├── claudiv.json          # Claudiv config (optional)
-├── package.json
-└── vite.config.ts
-```
-
-### .gitignore
-
-```gitignore
-# Claudiv generated files
-src/generated/
-
-# Claudiv metadata
-.claudiv/
-```
-
-## Usage Patterns
-
-### Basic HTML Generation
-
-```typescript
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    claudiv({
-      specFile: 'claudiv/app.cdml',
-      target: 'html'
-    })
-  ]
-});
-```
-
-```xml
-<!-- claudiv/app.cdml -->
-<app target="html">
-  <landing-page gen>
-    Hero section with gradient background,
-    feature cards, and call-to-action buttons
-  </landing-page>
-</app>
-```
-
-Generated: `src/generated/app.html`
-
-### React Components
-
-```typescript
-// vite.config.ts
-import react from '@vitejs/plugin-react';
-import { claudiv } from '@claudiv/vite-sdk';
-
-export default defineConfig({
-  plugins: [
-    react(),
-    claudiv({
-      specFile: 'claudiv/app.cdml',
-      target: 'react',
-      outputDir: 'src/components'
-    })
-  ]
-});
-```
-
-```xml
-<!-- claudiv/app.cdml -->
-<app target="react">
-  <Dashboard gen>
-    Analytics dashboard with charts using recharts
-  </Dashboard>
-</app>
-```
-
-Generated: `src/components/Dashboard.tsx`
-
-### Multi-File Setup
-
-```typescript
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    claudiv({
-      specFile: 'claudiv/**/*.cdml',  // Watch all .cdml files
-      outputDir: 'src/generated'
-    })
-  ]
-});
-```
-
-## API Mode Setup
-
-### Using Anthropic API
-
-1. Install @anthropic-ai/sdk:
-```bash
-npm install @anthropic-ai/sdk
-```
-
-2. Create `.env` file:
-```env
-ANTHROPIC_API_KEY=sk-ant-api03-...
-```
-
-3. Configure plugin:
-```typescript
-export default defineConfig({
-  plugins: [
-    claudiv({
-      mode: 'api',
-      specFile: 'claudiv/app.cdml'
-    })
-  ]
-});
-```
-
-## CLI Mode Setup
-
-### Using Claude Code Subscription
-
-1. Install Claude Code:
-```bash
-# Follow installation at https://claude.ai/code
-```
-
-2. Configure plugin:
-```typescript
-export default defineConfig({
-  plugins: [
-    claudiv({
-      mode: 'cli',  // Default mode
-      specFile: 'claudiv/app.cdml'
-    })
-  ]
-});
-```
-
-## Hot Module Replacement (HMR)
-
-The plugin automatically enables HMR for .cdml files:
-
-1. Edit your CDML file:
-```xml
-<!-- claudiv/app.cdml -->
-<button gen>Make it blue</button>
-```
-
-2. Save the file
-3. Browser automatically reloads with updated code
-4. No manual refresh needed!
-
-### HMR Behavior
-
-- **Full Reload:** Changes to .cdml files trigger full page reload
-- **Instant:** Vite's dev server provides sub-second feedback
-- **Automatic:** No configuration needed - works out of the box
-
-## Build-Time Generation
-
-During production builds, Claudiv generates code before bundling:
-
-```bash
-npm run build
-```
-
-**Build Process:**
-1. Parse all .cdml files
-2. Generate code to `outputDir`
-3. Vite bundles generated code
-4. Outputs production-ready assets
-
-## Advanced Usage
-
-### Custom Watcher
-
-```typescript
-import { ClaudivViteWatcher } from '@claudiv/vite-sdk';
-
-const watcher = new ClaudivViteWatcher({
-  specFile: 'custom-path/**/*.cdml'
-});
-
-watcher.on('change', (file) => {
-  console.log('CDML file changed:', file);
-});
-
-watcher.start();
-```
-
-### Programmatic Generation
-
-```typescript
-import { claudiv } from '@claudiv/vite-sdk';
-import { generateCode } from '@claudiv/core';
-
-// Use core package for custom logic
-const generated = await generateCode(response, pattern, context);
-```
-
-## Troubleshooting
-
-### Plugin Not Watching Files
-
-**Issue:** Changes to .cdml files don't trigger reloads
-
-**Solution:**
-```typescript
-// Ensure watch is enabled (default)
-claudiv({
-  watch: true,
-  specFile: 'claudiv/**/*.cdml'  // Correct glob pattern
-})
-```
-
-### Generated Files Not Found
-
-**Issue:** Import errors for generated files
-
-**Solution:**
-1. Check `outputDir` matches import paths
-2. Verify .cdml files have `gen` attributes
-3. Check Vite dev server logs for generation errors
-
-### API Key Not Found
-
-**Issue:** `ANTHROPIC_API_KEY` not detected
-
-**Solution:**
-```bash
-# Create .env file in project root
-echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
-```
-
-## Status
-
-⚠️ **Alpha Release** - Core functionality implemented, active development ongoing
-
-**Current Features:**
-- ✅ File watching with HMR
-- ✅ Basic code generation
-- ✅ Vite dev server integration
-
-**Planned Features:**
-- 🚧 Build-time generation optimization
-- 🚧 Source maps for debugging
-- 🚧 Multi-target support in single project
-- 🚧 Plugin hooks for customization
+## Bin Scripts
 
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Watch mode
-npm run dev
-
-# Clean dist
-npm run clean
-```
-
-## Contributing
-
-Contributions are welcome! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+| Script | Purpose |
+|--------|---------|
+| `claudiv-vite-init` | Project initialization |
+| `claudiv-vite-dev` | Dev mode watcher |
+| `claudiv-vite-gen` | One-shot generation |
+| `claudiv-vite-mode` | Mode selection prompt |
 
 ## License
 
-MIT © 2026 Amir Guterman
-
-See [LICENSE](./LICENSE) for details.
-
-## Links
-
-- **Homepage:** [https://claudiv.org](https://claudiv.org)
-- **GitHub:** [https://github.com/claudiv-ai/vite-sdk](https://github.com/claudiv-ai/vite-sdk)
-- **npm:** [https://npmjs.com/package/@claudiv/vite-sdk](https://npmjs.com/package/@claudiv/vite-sdk)
-- **Documentation:** [https://docs.claudiv.org/vite-sdk](https://docs.claudiv.org/vite-sdk)
-
-## Related Packages
-
-- [@claudiv/core](https://npmjs.com/package/@claudiv/core) - Core generation engine
-- [@claudiv/cli](https://npmjs.com/package/@claudiv/cli) - CLI tool for CDML generation
-
----
-
-**Add declarative AI-powered generation to your Vite projects!**
+MIT

package/bin/dev.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+/**
+ * claudiv-vite-dev — Watch .cdml files and process changes.
+ */
+
+import { runDev } from '../dist/dev-runner.js';
+import { readFile } from 'fs/promises';
+import { join, existsSync } from 'path';
+
+const projectRoot = process.cwd();
+
+// Load config
+let opts = {};
+const configPath = join(projectRoot, '.claudiv', 'config.json');
+try {
+  if (existsSync(configPath)) {
+    opts = JSON.parse(await readFile(configPath, 'utf-8'));
+  }
+} catch {
+  // Use defaults
+}
+
+runDev(projectRoot, opts).catch((err) => {
+  console.error(`[claudiv:dev] Fatal: ${err.message}`);
+  process.exit(1);
+});

package/bin/gen.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+/**
+ * claudiv-vite-gen — One-shot generation from .cdml files.
+ */
+
+import { runGen } from '../dist/gen-runner.js';
+import { readFile } from 'fs/promises';
+import { join, existsSync } from 'path';
+
+const projectRoot = process.cwd();
+
+// Load config
+let opts = {};
+const configPath = join(projectRoot, '.claudiv', 'config.json');
+try {
+  if (existsSync(configPath)) {
+    opts = JSON.parse(await readFile(configPath, 'utf-8'));
+  }
+} catch {
+  // Use defaults
+}
+
+// Check for --dry-run flag
+if (process.argv.includes('--dry-run')) {
+  opts.dryRun = true;
+}
+
+// Check for --scope flag
+const scopeIdx = process.argv.indexOf('--scope');
+if (scopeIdx !== -1 && process.argv[scopeIdx + 1]) {
+  opts.scope = process.argv[scopeIdx + 1];
+}
+
+runGen(projectRoot, opts).catch((err) => {
+  console.error(`[claudiv:gen] Fatal: ${err.message}`);
+  process.exit(1);
+});

package/bin/init.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * claudiv-vite-init — Initialize a Vite project for Claudiv.
+ */
+
+import { ViteSdk } from '../dist/index.js';
+
+const sdk = new ViteSdk();
+const projectRoot = process.cwd();
+
+const result = await sdk.init(projectRoot);
+
+if (result.success) {
+  console.log('Claudiv initialized successfully!');
+  console.log('Files created:');
+  for (const file of result.filesCreated) {
+    console.log(`  + ${file}`);
+  }
+  console.log('');
+  console.log('Next steps:');
+  console.log('  npm run claudiv:dev   — watch & generate');
+  console.log('  npm run claudiv:gen   — one-shot generation');
+  console.log('  npm run claudiv:mode  — switch CLI/API mode');
+} else {
+  console.error('Initialization failed:');
+  for (const w of result.warnings || []) {
+    console.error(`  ${w}`);
+  }
+  process.exit(1);
+}

package/bin/mode.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+/**
+ * claudiv-vite-mode — Select CLI or API mode.
+ */
+
+import { selectMode } from '../dist/mode-selector.js';
+
+selectMode(process.cwd()).catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/bin/postinstall.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall hook: adds only claudiv:init to user's package.json.
+ * Other scripts are added during init.
+ */
+
+import { readFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+const projectRoot = process.env.INIT_CWD || process.cwd();
+
+async function main() {
+  try {
+    const pkgPath = join(projectRoot, 'package.json');
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+
+    if (!pkg.scripts) pkg.scripts = {};
+
+    // Only add init script on postinstall
+    if (!pkg.scripts['claudiv:init']) {
+      pkg.scripts['claudiv:init'] = 'claudiv-vite-init';
+      await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+      console.log('[claudiv] Added claudiv:init script. Run: npm run claudiv:init');
+    }
+  } catch {
+    // Silently skip if package.json can't be modified
+  }
+}
+
+main();

package/dist/cache.d.ts

@@ -0,0 +1,12 @@
+/**
+ * In-memory CDML content cache for diff-based change detection.
+ */
+export declare class CdmlCache {
+    private entries;
+    get(key: string): string | undefined;
+    set(key: string, content: string): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAA6B;IAE5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,KAAK,IAAI,IAAI;CAGd"}

package/dist/cache.js

@@ -0,0 +1,22 @@
+/**
+ * In-memory CDML content cache for diff-based change detection.
+ */
+export class CdmlCache {
+    entries = new Map();
+    get(key) {
+        return this.entries.get(key);
+    }
+    set(key, content) {
+        this.entries.set(key, content);
+    }
+    has(key) {
+        return this.entries.has(key);
+    }
+    delete(key) {
+        return this.entries.delete(key);
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,SAAS;IACZ,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE5C,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,OAAe;QAC9B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/detector.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Vite framework detector.
+ *
+ * Checks if a project uses Vite and extracts project metadata.
+ */
+import type { FrameworkDetector } from '@claudiv/core';
+export declare class ViteDetector implements FrameworkDetector {
+    detect(projectRoot: string): Promise<boolean>;
+    getAppName(projectRoot: string): Promise<string>;
+    getSourcePaths(projectRoot: string): Promise<string[]>;
+    getIgnorePatterns(): string[];
+}
+//# sourceMappingURL=detector.d.ts.map

package/dist/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../src/detector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,qBAAa,YAAa,YAAW,iBAAiB;IAC9C,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4B7C,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAahD,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAa5D,iBAAiB,IAAI,MAAM,EAAE;CAQ9B"}