@eldrin-project/eldrin-app-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eldrin Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# @eldrin-project/eldrin-app-core
+
+[![npm version](https://img.shields.io/npm/v/@eldrin-project/eldrin-app-core.svg)](https://www.npmjs.com/package/@eldrin-project/eldrin-app-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
+
+Standard library for building Eldrin marketplace apps. Provides database migrations, React hooks for D1 database access, single-spa lifecycle management, and CLI tools for releasing to the Eldrin marketplace.
+
+## Features
+
+- **Zero-config migrations** - SQL migrations run automatically during app bootstrap
+- **Type-safe database access** - React hooks with full TypeScript support
+- **Single-spa compatible** - Seamless integration with micro-frontend architecture
+- **Cloudflare Workers ready** - Built for D1 databases and Workers runtime
+- **CLI tools included** - Release and submit apps to the Eldrin marketplace
+
+## Installation
+
+```bash
+npm install @eldrin-project/eldrin-app-core
+```
+
+## Quick Start
+
+### 1. Create your app entry point
+
+```tsx
+// src/index.tsx
+import { createApp } from '@eldrin-project/eldrin-app-core';
+import migrations from 'virtual:eldrin/migrations';
+import App from './App';
+
+export const { bootstrap, mount, unmount } = createApp({
+  name: 'my-app',
+  root: App,
+  migrations,
+});
+```
+
+### 2. Configure Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { eldrinPlugin } from '@eldrin-project/eldrin-app-core/vite';
+
+export default defineConfig({
+  plugins: [
+    eldrinPlugin({
+      migrationsDir: './migrations',
+      seedsDir: './seeds',
+    }),
+  ],
+});
+```
+
+### 3. Add TypeScript support for virtual modules
+
+```ts
+// src/vite-env.d.ts
+/// <reference types="@eldrin-project/eldrin-app-core/vite-env" />
+```
+
+### 4. Use the database in components
+
+```tsx
+import { useDatabase } from '@eldrin-project/eldrin-app-core';
+
+function InvoiceList() {
+  const db = useDatabase();
+  const [invoices, setInvoices] = useState([]);
+
+  useEffect(() => {
+    if (!db) return;
+    db.prepare('SELECT * FROM invoices ORDER BY created_at DESC')
+      .all()
+      .then(({ results }) => setInvoices(results));
+  }, [db]);
+
+  return <ul>{invoices.map(inv => <li key={inv.id}>{inv.name}</li>)}</ul>;
+}
+```
+
+## Migrations
+
+Create SQL migration files in your `migrations/` directory:
+
+```
+migrations/
+├── 20250101120000-create-invoices.sql
+├── 20250101120000-create-invoices.rollback.sql
+└── 20250102100000-add-status-column.sql
+```
+
+Migration filenames must follow the pattern: `YYYYMMDDHHMMSS-description.sql`
+
+Migrations run automatically during the app bootstrap phase. The system tracks executed migrations in the `_eldrin_migrations` table with SHA-256 checksums to detect tampering.
+
+### Migration Hooks
+
+```tsx
+export const { bootstrap, mount, unmount } = createApp({
+  name: 'my-app',
+  root: App,
+  migrations,
+  onMigrationsComplete: (result) => {
+    console.log(`Executed ${result.executed} migrations`);
+  },
+  onMigrationError: (error) => {
+    console.error('Migration failed:', error);
+  },
+});
+```
+
+## API Reference
+
+### createApp(options)
+
+Creates a single-spa compatible app lifecycle.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | `string` | Unique app identifier |
+| `root` | `React.ComponentType` | Root React component |
+| `migrations` | `MigrationFile[]` | Migration files (from virtual module) |
+| `onMigrationsComplete` | `(result) => void` | Called after successful migrations |
+| `onMigrationError` | `(error) => void` | Called if migrations fail |
+
+### useDatabase()
+
+React hook that returns the D1 database instance or `null`.
+
+```tsx
+const db = useDatabase();
+```
+
+### useDatabaseContext()
+
+React hook that returns the full database context including migration status.
+
+```tsx
+const { db, migrationsComplete, migrationResult } = useDatabaseContext();
+```
+
+### useMigrationsComplete()
+
+React hook that returns `true` when migrations have finished.
+
+```tsx
+const ready = useMigrationsComplete();
+if (!ready) return <Loading />;
+```
+
+## CLI Tools
+
+### eldrin-release
+
+Prepares your app for marketplace submission.
+
+```bash
+npx eldrin-release [options]
+
+Options:
+  -t, --type <type>      Bump version: patch, minor, or major
+  -v, --version <ver>    Set explicit version
+  --skip-build           Skip the build step
+  -m, --manifest <path>  Path to manifest file
+  -o, --output <path>    Output directory
+```
+
+Creates a release package at `dist/release/{developerId}/{appId}/v{version}/` containing:
+- `eldrin-app.manifest.json` - App metadata
+- `bundle.js` - Built app bundle
+- `deploy-bundle.json` - Worker + client assets (if applicable)
+- `migrations/` - Migration files with checksums
+
+### eldrin-submit
+
+Submits a release to the Eldrin marketplace.
+
+```bash
+npx eldrin-submit -d ./dist/release/eldrin.io/my-app/v1.0.0
+
+Options:
+  -d, --release-dir <dir>  Release directory to submit
+  -k, --api-key <key>      Developer API key
+  --developer-id <id>      Developer ID
+  --dry-run                Preview without submitting
+```
+
+Environment variables:
+- `ELDRIN_API_KEY` - Your developer API key
+- `ELDRIN_DEVELOPER_ID` - Your developer ID
+- `ELDRIN_MARKETPLACE_URL` - Marketplace URL (default: https://eldrin.io)
+
+## Configuration
+
+Create `.eldrinrc.json` in your project root:
+
+```json
+{
+  "developerId": "your-developer-id",
+  "marketplaceUrl": "https://eldrin.io",
+  "manifestPath": "./eldrin-app.manifest.json",
+  "migrationsDir": "./migrations",
+  "buildCommand": "npm run build:lib",
+  "clientDir": "dist/client",
+  "workerEntry": "dist/worker/index.js"
+}
+```
+
+## App Manifest
+
+Create `eldrin-app.manifest.json`:
+
+```json
+{
+  "id": "my-app",
+  "name": "My App",
+  "version": "1.0.0",
+  "description": "Description of my app",
+  "developer": {
+    "id": "your-developer-id",
+    "name": "Your Name"
+  },
+  "entry": "bundle.js"
+}
+```
+
+## Requirements
+
+- Node.js 18.0.0 or later
+- React 18.x or 19.x
+- Vite 6.x or 7.x
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.

package/dist/cli/release.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Release Script for Eldrin Apps
+ *
+ * Prepares app for marketplace submission by:
+ * 1. Building the library bundle
+ * 2. Generating migration manifest with checksums
+ * 3. Creating deployment bundle (worker + client assets)
+ * 4. Copying files to release directory
+ *
+ * Usage: npx eldrin-release [options]
+ *
+ * Output structure:
+ *   dist/release/{developerId}/{appId}/
+ *   ├── migrations/                    # All migrations at app level (shared across versions)
+ *   │   ├── index.json
+ *   │   └── *.sql
+ *   └── v{version}/
+ *       ├── eldrin-app.manifest.json
+ *       ├── bundle.js
+ *       └── deploy-bundle.json         (if client assets exist)
+ */
+type BumpType = 'patch' | 'minor' | 'major';
+interface ReleaseOptions {
+    version?: string;
+    bumpType?: BumpType;
+    skipBuild?: boolean;
+    manifestPath?: string;
+    bundlePath?: string;
+    migrationsDir?: string;
+    outputDir?: string;
+    marketplaceUrl?: string;
+}
+declare function release(options?: ReleaseOptions): Promise<void>;
+
+export { release };