nuxt-studio 0.0.0

package/README.md

@@ -0,0 +1,241 @@
+# Nuxt Studio
+
+[![npm version](https://img.shields.io/npm/v/nuxt-studio.svg?style=flat&colorA=020420&colorB=EEEEEE)](https://npmjs.com/package/nuxt-studio)
+[![npm downloads](https://img.shields.io/npm/dm/nuxt-studio.svg?style=flat&colorA=020420&colorB=EEEEEE)](https://npm.chart.dev/nuxt-studio)
+[![License](https://img.shields.io/npm/l/nuxt-studio.svg?style=flat&colorA=020420&colorB=EEEEEE)](https://npmjs.com/package/nuxt-studio)
+
+---
+
+## ⚠️ Alpha Release
+
+> **Current Status: Alpha Testing**
+>
+> Nuxt Studio is currently in **alpha** and uses the Monaco code editor for content editing. This phase focuses on testing and stabilizing core functionality:
+>
+> - ✅ File operations (create, edit, delete, rename)
+> - ✅ Content editing with Monaco editor
+> - ✅ Media management and uploads
+> - ✅ GitHub authentication and publishing workflow
+>
+> **🎨 Visual Editor Coming Soon**
+>
+> Once all file operations and GitHub publishing workflows are tested and stable, we'll release **Phase 2 (Beta)** with the full visual editor for Markdown, Vue components, and medias...
+
+---
+
+> Visual edition in production for your [Nuxt Content](https://content.nuxt.com) website.
+
+Originally offered as a standalone premium platform at https://nuxt.studio, Studio has evolved into a free, open-source, and self-hostable Nuxt module. Enable your entire team to edit website content right in production.
+
+**Current Features (Alpha):**
+
+- 💻 **Monaco Code Editor** - Code editor for enhanced Markdown with MDC syntax, YAML, and JSON
+- 🔄 **Real-time Preview** - See your changes instantly on your production website
+- 🔐 **GitHub Authentication** - Secure OAuth-based login with GitHub
+- 📝 **File Management** - Create, edit, delete, and rename content files (`content/` directory)
+- 🖼️ **Media Management** - Centralized media library for all your assets (`public/` directory)
+- 🌳 **Git Integration** - Commit changes directly from your production website and just wait your CI/CD pipeline to deploy your changes
+- 🚀 **Development Mode** - Directly edit your content files and media files in your local filesystem using the module interface
+
+**Coming in Beta:**
+- 🎨 **Visual Editor** - Visual editor for content management, from text edition to media management - all without touching code
+- 🔐 **Google OAuth Authentication** - Secure OAuth-based login with Google
+
+**Future Features:**
+- 📂 **Collections view** - View and manage your content collections in a unified interface
+- 🖼️ **Media optimization** - Optimize your media files in the editor
+- 🤖 **AI Content Assistant** — Receive smart, AI-powered suggestions to enhance your content creation flow
+- 💡 **Community-driven Features** — Have an idea? [Share your suggestions](https://github.com/nuxt-content/studio/discussions) to shape the future of Nuxt Studio
+
+[📖 Documentation](https://content.nuxt.com/studio)
+[🎮 Live Demo](https://docus.dev/admin)
+
+## Quick Setup
+
+> **Note**: This alpha release provides a Monaco-based code editor. The visual WYSIWYG editor will be available in the beta release.
+
+### 1. Module Installation
+
+Install the module in your Nuxt application with one command:
+
+```bash
+npx nuxi module add nuxt-studio
+```
+
+Add it to your `nuxt.config` and configure your repository.
+
+```ts
+export default defineNuxtConfig({
+  modules: [
+    '@nuxt/content',
+    'nuxt-studio'
+  ],
+  studio: {
+    // Your configuration
+    repository: {
+      provider: 'github', // default: only GitHub supported currently
+      owner: 'your-username', // your GitHub owner
+      repo: 'your-repo', // your GitHub repository name
+      branch: 'main',
+      rootDir: '' // optional: location of your content app
+    }
+  }
+})
+```
+
+### 2. Create a GitHub OAuth App
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Click **"New OAuth App"**
+3. Fill in the application details:
+   - **Application name**: Your App Name
+   - **Homepage URL**: Your website homepage URL
+   - **Authorization callback URL**: `${YOUR_WEBSITE_URL}/${options.route}/auth/github` (default: `${YOUR_WEBSITE_URL}/_studio/auth/github`)
+4. Copy the **Client ID** and generate a **Client Secret**
+5. Add them to your deployment environment variables (see next section)
+
+### 3. Environment Variables
+
+Nuxt Studio requires environment variables for authentication and publication on your repository.
+
+Add the previsously generated Client ID and Client Secret to your deployment environment variables.
+
+```bash
+STUDIO_GITHUB_CLIENT_ID=your_github_client_id
+STUDIO_GITHUB_CLIENT_SECRET=your_github_client_secret
+```
+
+## Configuration
+
+Configure Nuxt Studio in your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-studio'],
+  studio: {
+    // Studio admin login route
+    route: '/_studio', // default
+
+    // Git repository configuration (required)
+    repository: {
+      provider: 'github', // only GitHub is supported currently (default)
+      owner: 'your-username', // your GitHub owner
+      repo: 'your-repo', // your GitHub repository name
+      branch: 'main', // your GitHub branch
+      rootDir: '' // optional: root directory for
+    },
+  }
+})
+```
+
+## Development Mode
+
+Nuxt Studio includes an **experimental** development mode that enables real-time file system synchronization:
+
+> You must setup a local GitHub OAuth App to use this feature (pointing to `http://localhost:3000` as callback URL).
+
+```ts
+export default defineNuxtConfig({
+  studio: {
+    development: {
+      sync: true // Enable development mode
+    }
+  }
+})
+```
+
+When enabled, Nuxt Studio will:
+
+- ✅ Write changes directly to your local `content/` directory
+- ✅ Write media changes to your local `public/` directory
+- ❌ Listen for file system changes and update the editor
+- ❌ Commit changes to your repository (use your classical workflow instead)
+
+## Contributing
+You must clone the repository and create a local GitHub OAuth App (pointing to `http://localhost:3000` as callback URL).
+
+Set your GitHub OAuth credentials in the `.env` file.
+
+### Development Setup
+
+```bash
+# Install dependencies
+pnpm install
+
+# Generate type stubs
+pnpm dev:prepare
+
+# Build the app and service worker
+pnpm prepack
+
+# Terminal 1: Start the playground
+pnpm dev
+
+# Terminal 2: Start the app dev server
+pnpm dev:app
+
+# Login at http://localhost:3000/admin
+```
+
+### Project Structure
+
+```
+studio/
+├── src/
+│   ├── app/           # Studio editor Vue app
+│   └── module/        # Nuxt module
+├── playground/        # Development playground
+│   ├── docus/         # Docus example
+│   └── minimal/       # Minimal example
+```
+
+### Testing
+
+```bash
+# Run tests
+pnpm test
+
+# Run type checking
+pnpm typecheck
+
+# Run linter
+pnpm lint
+```
+
+## Roadmap
+
+### ✅ Phase 1 - Alpha (Current)
+- [x] Monaco code editor
+- [x] File operations (create, edit, delete, rename)
+- [x] Media management
+- [x] GitHub authentication
+- [x] Development mode (**experimental**)
+- [x] Git integration
+- [x] Real-time preview
+
+### 🚧 Phase 2 - Beta (In Development)
+- [ ] Google OAuth authentication
+- [ ] Visual editor
+- [ ] Frontmatter edition as form
+- [ ] Vue Component edition (props, slots)
+
+### 🔮 Future
+
+- [ ] GitLab provider support
+- [ ] Other provider support
+- [ ] Advanced conflict resolution
+- [ ] Pull request generation (from a branch to the main one)
+- [ ] AI-powered content suggestions
+
+## Links
+
+- 📖 [Documentation](https://content.nuxt.com/studio)
+- 🐛 [Report a Bug](https://github.com/nuxt-content/studio/issues)
+- 💡 [Feature Request](https://github.com/nuxt-content/studio/discussions)
+- 🗨️ [Discussions](https://github.com/nuxt-content/studio/discussions)
+- 🆇 [Twitter](https://x.com/nuxtstudio)
+- 🦋 [Bluesky](https://bsky.app/profile/nuxt.com)
+
+## License
+
+Published under the [MIT](LICENSE) license.

package/dist/app/main.d.ts

@@ -0,0 +1,342 @@
+import { CollectionItemBase } from '@nuxt/content';
+import { ComponentData } from 'nuxt-component-meta';
+import { DataCollectionItemBase } from '@nuxt/content';
+import { PageCollectionItemBase } from '@nuxt/content';
+import { RouteLocationNormalized } from 'vue-router';
+
+export declare type ActionHandlerParams = {
+    [StudioItemActionId.CreateDocumentFolder]: CreateFolderParams;
+    [StudioItemActionId.CreateMediaFolder]: CreateFolderParams;
+    [StudioItemActionId.CreateDocument]: CreateFileParams;
+    [StudioItemActionId.UploadMedia]: UploadMediaParams;
+    [StudioItemActionId.RevertItem]: TreeItem;
+    [StudioItemActionId.RenameItem]: TreeItem | RenameFileParams;
+    [StudioItemActionId.DeleteItem]: TreeItem;
+    [StudioItemActionId.DuplicateItem]: TreeItem;
+    [StudioItemActionId.RevertAllItems]: never;
+    [StudioBranchActionId.PublishBranch]: PublishBranchParams;
+};
+
+export declare enum AudioFileExtension {
+    MP3 = "mp3",
+    WAV = "wav",
+    OGG = "ogg",
+    M4A = "m4a",
+    AAC = "aac",
+    FLAC = "flac"
+}
+
+export declare interface BaseItem {
+    id: string;
+    extension: string;
+    stem: string;
+    path?: string;
+}
+
+export declare interface CommitFilesOptions extends GitBaseOptions {
+    files: RawFile[];
+    message: string;
+}
+
+export declare interface ComponentMeta {
+    name: string;
+    path: string;
+    meta: {
+        props: ComponentData['meta']['props'];
+        slots: ComponentData['meta']['slots'];
+        events: ComponentData['meta']['events'];
+    };
+}
+
+export declare interface ContentConflict {
+    githubContent: string;
+    localContent: string;
+}
+
+export declare enum ContentFileExtension {
+    Markdown = "md",
+    YAML = "yaml",
+    YML = "yml",
+    JSON = "json"
+}
+
+export declare interface CreateFileParams {
+    fsPath: string;
+    content: string;
+}
+
+export declare interface CreateFolderParams {
+    fsPath: string;
+}
+
+export declare interface DatabaseDataItem extends DataCollectionItemBase, BaseItem {
+    [key: string]: unknown;
+}
+
+export declare interface DatabaseItem extends CollectionItemBase, BaseItem {
+    [key: string]: unknown;
+}
+
+export declare interface DatabasePageItem extends PageCollectionItemBase, BaseItem {
+    path: string;
+    [key: string]: unknown;
+}
+
+declare const _default: {};
+export default _default;
+
+export declare interface DraftItem<T = DatabaseItem | MediaItem> {
+    id: string;
+    fsPath: string;
+    status: DraftStatus;
+    githubFile?: GithubFile;
+    original?: T;
+    modified?: T;
+    /**
+     * - Buffer media content
+     */
+    raw?: string | Buffer;
+    /**
+     * Version of the draft
+     * Incremented when the draft is updated
+     * Used to detect changes when the draft is saved
+     */
+    version?: number;
+    /**
+     * Content conflict detection
+     */
+    conflict?: ContentConflict;
+}
+
+export declare enum DraftStatus {
+    Deleted = "deleted",
+    Created = "created",
+    Updated = "updated",
+    Pristine = "pristine"
+}
+
+export declare interface ExtensionConfig {
+    allowed: string[];
+    default?: string;
+    editable: boolean;
+}
+
+export declare interface GitBaseOptions {
+    owner: string;
+    repo: string;
+    branch: string;
+    authorName: string;
+    authorEmail: string;
+}
+
+export declare interface GithubFile {
+    name: string;
+    path: string;
+    sha: string;
+    size: number;
+    url: string;
+    html_url: string;
+    git_url: string;
+    download_url: string;
+    type: string;
+    content?: string;
+    encoding?: string;
+    _links: {
+        self: string;
+        git: string;
+        html: string;
+    };
+}
+
+export declare interface GitOptions extends GitBaseOptions {
+    rootDir: string;
+    token: string;
+}
+
+export declare enum ImageFileExtension {
+    PNG = "png",
+    JPG = "jpg",
+    JPEG = "jpeg",
+    SVG = "svg",
+    WEBP = "webp",
+    ICO = "ico",
+    GIF = "gif"
+}
+
+export declare type MediaFileExtension = ImageFileExtension | AudioFileExtension | VideoFileExtension;
+
+export declare interface MediaItem extends BaseItem {
+    [key: string]: unknown;
+}
+
+export declare interface PublishBranchParams {
+    commitMessage: string;
+}
+
+export declare interface RawFile {
+    path: string;
+    content: string | null;
+    status: DraftStatus;
+    encoding?: 'utf-8' | 'base64';
+}
+
+export declare interface RenameFileParams {
+    item: TreeItem;
+    newFsPath: string;
+}
+
+export declare interface Repository {
+    provider: 'github';
+    owner: string;
+    repo: string;
+    branch: string;
+    rootDir: string;
+}
+
+export declare interface StudioAction<K extends StudioItemActionId | StudioBranchActionId> {
+    id: K;
+    label: string;
+    icon: string;
+    tooltip: string;
+    handler?: (args: ActionHandlerParams[K]) => void;
+}
+
+export declare interface StudioActionInProgress {
+    id: StudioItemActionId | StudioBranchActionId;
+    item?: TreeItem;
+}
+
+export declare enum StudioBranchActionId {
+    PublishBranch = "publish-branch"
+}
+
+export declare interface StudioConfig {
+    syncEditorAndRoute: boolean;
+    showTechnicalMode: boolean;
+}
+
+export declare enum StudioFeature {
+    Content = "content",
+    Media = "media"
+}
+
+export declare interface StudioHost {
+    meta: {
+        dev: boolean;
+        components: () => ComponentMeta[];
+    };
+    on: {
+        routeChange: (fn: (to: RouteLocationNormalized, from: RouteLocationNormalized) => void) => void;
+        mounted: (fn: () => void) => void;
+        beforeUnload: (fn: (event: BeforeUnloadEvent) => void) => void;
+        colorModeChange: (fn: (colorMode: 'light' | 'dark') => void) => void;
+        manifestUpdate: (fn: (id: string) => void) => void;
+        documentUpdate: (fn: (id: string, type: 'remove' | 'update') => void) => void;
+        mediaUpdate: (fn: (id: string, type: 'remove' | 'update') => void) => void;
+    };
+    ui: {
+        colorMode: 'light' | 'dark';
+        activateStudio: () => void;
+        deactivateStudio: () => void;
+        expandSidebar: () => void;
+        collapseSidebar: () => void;
+        updateStyles: () => void;
+    };
+    repository: Repository;
+    document: {
+        get: (id: string) => Promise<DatabaseItem>;
+        getFileSystemPath: (id: string) => string;
+        list: () => Promise<DatabaseItem[]>;
+        upsert: (id: string, document: DatabaseItem) => Promise<void>;
+        create: (fsPath: string, content: string) => Promise<DatabaseItem>;
+        delete: (id: string) => Promise<void>;
+        detectActives: () => Array<{
+            id: string;
+            title: string;
+        }>;
+    };
+    media: {
+        get: (id: string) => Promise<MediaItem>;
+        getFileSystemPath: (id: string) => string;
+        list: () => Promise<MediaItem[]>;
+        upsert: (id: string, media: MediaItem) => Promise<void>;
+        delete: (id: string) => Promise<void>;
+    };
+    user: {
+        get: () => StudioUser;
+    };
+    app: {
+        getManifestId: () => Promise<string>;
+        requestRerender: () => void;
+        navigateTo: (path: string) => void;
+    };
+}
+
+export declare enum StudioItemActionId {
+    CreateDocumentFolder = "create-document-folder",
+    CreateMediaFolder = "create-media-folder",
+    CreateDocument = "create-document",
+    UploadMedia = "upload-media",
+    RevertItem = "revert-item",
+    RenameItem = "rename-item",
+    DeleteItem = "delete-item",
+    DuplicateItem = "duplicate-item",
+    RevertAllItems = "revert-all-items"
+}
+
+export declare interface StudioLocation {
+    active: boolean;
+    feature: StudioFeature;
+    fsPath: string;
+}
+
+export declare interface StudioUser {
+    githubId: string;
+    githubToken: string;
+    name: string;
+    avatar: string;
+    email: string;
+    provider: 'github' | 'google';
+}
+
+export declare interface TreeItem {
+    name: string;
+    fsPath: string;
+    type: 'file' | 'directory' | 'root';
+    prefix: number | null;
+    collections: string[];
+    status?: TreeStatus;
+    routePath?: string;
+    children?: TreeItem[];
+    hide?: boolean;
+}
+
+export declare enum TreeRootId {
+    Content = "content",
+    Media = "public-assets"
+}
+
+export declare enum TreeStatus {
+    Deleted = "deleted",
+    Created = "created",
+    Updated = "updated",
+    Renamed = "renamed",
+    Opened = "opened"
+}
+
+export declare interface UploadMediaParams {
+    parentFsPath: string;
+    files: File[];
+}
+
+export declare type UseStudioHost = () => StudioHost;
+
+export declare enum VideoFileExtension {
+    MP4 = "mp4",
+    MOV = "mov",
+    AVI = "avi",
+    MKV = "mkv",
+    WEBM = "webm"
+}
+
+export { }