@mgks/docmd 0.3.6 → 0.3.8

package/src/commands/init.js

@@ -1,162 +1,165 @@
-// Source file from the docmd project — https://github.com/mgks/docmd
+// Source file from the docmd project — https://github.com/docmd-io/docmd
 
-const fs = require('fs-extra');
+const fs = require('../core/fs-utils');
 const path = require('path');
 const readline = require('readline');
+const { version } = require('../../package.json');
 
-const defaultConfigContent = `// docmd.config.js: basic config for docmd
+const defaultConfigContent = `// docmd.config.js
 module.exports = {
-  // Core Site Metadata
-  siteTitle: 'docmd',
-  // Define a base URL for your site, crucial for SEO and absolute paths
-  // No trailing slash
-  siteUrl: '', // Replace with your actual deployed URL
+  // --- Core Metadata ---
+  siteTitle: 'My Documentation',
+  siteUrl: '', // e.g. https://mysite.com (Critical for SEO/Sitemap)
 
-  // Logo Configuration
+  // --- Branding ---
   logo: {
-    light: 'assets/images/docmd-logo-light.png', // Path relative to outputDir root
-    dark: 'assets/images/docmd-logo-dark.png',   // Path relative to outputDir root
-    alt: 'docmd logo',                      // Alt text for the logo
-    href: './',                              // Link for the logo, defaults to site root
+    light: 'assets/images/docmd-logo-dark.png',
+    dark: 'assets/images/docmd-logo-light.png',
+    alt: 'Logo',
+    href: './',
   },
+  favicon: 'assets/favicon.ico',
 
-  // Directory Configuration
-  srcDir: 'docs',       // Source directory for Markdown files
-  outputDir: 'site',    // Directory for generated static site
-
-  // Search Configuration
-  search: true,        // Enable/disable search functionality
-
-  // Build Options
-  minify: true,        // Enable/disable HTML/CSS/JS minification
+  // --- Source & Output ---
+  srcDir: 'docs',
+  outputDir: 'site',
 
-  // Sidebar Configuration
-  sidebar: {
-    collapsible: true,        // or false to disable
-    defaultCollapsed: false,  // or true to start collapsed
-  },
-
-  // Theme Configuration
+  // --- Theme & Layout ---
   theme: {
-    name: 'sky',            // Themes: 'default', 'sky'
-    defaultMode: 'light',   // Initial color mode: 'light' or 'dark'
-    enableModeToggle: true, // Show UI button to toggle light/dark modes
-    positionMode: 'top', // 'top' or 'bottom' for the theme toggle
-    codeHighlight: true,    // Enable/disable codeblock highlighting and import of highlight.js
-    customCss: [            // Array of paths to custom CSS files
-      // 'assets/css/custom.css', // Custom TOC styles
-    ]
+    name: 'sky',            // Options: 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'system',  // 'light', 'dark', or 'system'
+    enableModeToggle: true, // Show mode toggle button
+    positionMode: 'top',    // 'top' or 'bottom'
+    codeHighlight: true,    // Enable Highlight.js
+    customCss: [],          // e.g. ['assets/css/custom.css']
   },
 
-  // Custom JavaScript Files
-  customJs: [  // Array of paths to custom JS files, loaded at end of body
-    // 'assets/js/custom-script.js', // Paths relative to outputDir root
-    'assets/js/docmd-image-lightbox.js', // Image lightbox functionality
-  ],
+  // --- Features ---
+  search: true,           // Built-in offline search
+  minify: true,           // Minify HTML/CSS/JS in build
+  autoTitleFromH1: true,  // Auto-generate page title from first H1
+  copyCode: true,         // Show "copy" button on code blocks
+  pageNavigation: true,   // Prev/Next buttons at bottom
 
-  // Content Processing
-  autoTitleFromH1: true, // Set to true to automatically use the first H1 as page title
-  copyCode: true, // Enable/disable the copy code button on code blocks
+  // --- Navigation (Sidebar) ---
+  navigation: [
+    { title: 'Introduction', path: '/', icon: 'home' },
+    {
+      title: 'Guide',
+      icon: 'book-open',
+      collapsible: true,
+      children: [
+        { title: 'Getting Started', path: 'https://docs.docmd.io/getting-started/installation', icon: 'rocket', external: true },
+        { title: 'Configuration', path: 'https://docs.docmd.io/configuration', icon: 'settings', external: true },
+      ],
+    },
+    { title: 'Live Editor', path: 'https://live.docmd.io', icon: 'pencil-ruler', external: true },
+    { title: 'GitHub', path: 'https://github.com/docmd-io/docmd', icon: 'github', external: true },
+  ],
 
-  // Plugins Configuration
-  // Plugins are configured here. docmd will look for these keys.
+  // --- Plugins ---
   plugins: {
-    // SEO Plugin Configuration
-    // Most SEO data is pulled from page frontmatter (title, description, image, etc.)
-    // These are fallbacks or site-wide settings.
     seo: {
-      // Default meta description if a page doesn't have one in its frontmatter
-      defaultDescription: 'docmd is a Node.js command-line tool for generating beautiful, lightweight static documentation sites from Markdown files.',
-      openGraph: { // For Facebook, LinkedIn, etc.
-        // siteName: 'docmd Documentation', // Optional, defaults to config.siteTitle
-        // Default image for og:image if not specified in page frontmatter
-        // Path relative to outputDir root
-        defaultImage: 'assets/images/docmd-preview.png',
+      defaultDescription: 'Documentation built with docmd.',
+      openGraph: {
+        defaultImage: '',   // e.g. 'assets/images/og-image.png'
       },
-      twitter: { // For Twitter Cards
-        cardType: 'summary_large_image',     // 'summary', 'summary_large_image'
-        // siteUsername: '@docmd_handle',    // Your site's Twitter handle (optional)
-        // creatorUsername: '@your_handle',  // Default author handle (optional, can be overridden in frontmatter)
+      twitter: {
+        cardType: 'summary_large_image',
       }
     },
-    // Analytics Plugin Configuration
     analytics: {
-      // Google Analytics 4 (GA4)
       googleV4: {
-        measurementId: 'G-8QVBDQ4KM1' // Replace with your actual GA4 Measurement ID
+        measurementId: 'G-X9WTDL262N' // Replace with your Google Analytics Measurement ID
       }
     },
-    // Enable Sitemap plugin
     sitemap: {
-      defaultChangefreq: 'weekly',
-      defaultPriority: 0.8
+      defaultChangefreq: 'weekly',  // e.g. 'daily', 'weekly', 'monthly'
+      defaultPriority: 0.8          // Priority between 0.0 and 1.0
     }
-    // Add other future plugin configurations here by their key
   },
 
-  // "Edit this page" Link Configuration
+  // --- Footer ---
+  footer: '© ' + new Date().getFullYear() + ' My Project. Built with [docmd](https://docmd.io).',
+  
+  // --- Edit Link ---
   editLink: {
     enabled: false,
-    // The URL to the folder containing your docs in the git repo
-    // Note: It usually ends with /edit/main/docs or /blob/main/docs
-    baseUrl: 'https://github.com/mgks/docmd/edit/main/docs',
-    text: 'Edit this page on GitHub'
-  },
-
-  // Navigation Structure (Sidebar)
-  // Icons are kebab-case names from Lucide Icons (https://lucide.dev/)
-  navigation: [
-      { title: 'Welcome', path: '/', icon: 'home' }, // Corresponds to docs/index.md
-      {
-        title: 'Getting Started',
-        icon: 'rocket',
-        path: '#',
-        collapsible: true, // This makes the menu section collapsible
-        children: [
-          { title: 'Documentation', path: 'https://docmd.mgks.dev', icon: 'scroll', external: true },
-          { title: 'Installation', path: 'https://docmd.mgks.dev/getting-started/installation', icon: 'download', external: true },
-          { title: 'Basic Usage', path: 'https://docmd.mgks.dev/getting-started/basic-usage', icon: 'play', external: true },
-          { title: 'Content', path: 'https://docmd.mgks.dev/content', icon: 'layout-template', external: true },
-        ],
-      },
-      // External links:
-      { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
-      { title: 'Support the Project', path: 'https://github.com/sponsors/mgks', icon: 'heart', external: true },
-    ],
-    
-  pageNavigation: true, // Enable previous / next page navigation at the bottom of each page
-
-  // Sponsor Ribbon Configuration
-  Sponsor: {
-    enabled: false,
-    title: 'Support docmd',
-    link: 'https://github.com/sponsors/mgks',
-  },
-
-  // Footer Configuration
-  // Markdown is supported here.
-  footer: '© ' + new Date().getFullYear() + ' Project.',
-
-  // Favicon Configuration
-  // Path relative to outputDir root
-  favicon: 'assets/favicon.ico',
+    baseUrl: 'https://github.com/USERNAME/REPO/edit/main/docs',
+    text: 'Edit this page'
+  }
 };
 `;
 
 const defaultIndexMdContent = `---
 title: "Welcome"
-description: "Your documentation starts here."
+description: "Welcome to your new documentation site."
 ---
 
-# Hello, docmd!
+# Welcome to Your Docs
+
+Congratulations! You have successfully initialized a new **docmd** project.
+
+## 🚀 Quick Start
+
+You are currently viewing the content of \`docs/index.md\`.
 
-Start writing your Markdown content here.
+\`\`\`bash
+npm start   # Start the dev server
+docmd build # Build for production
+\`\`\`
+
+## ✨ Features Demo
+
+docmd comes with built-in components to make your documentation beautiful.
+
+::: callout tip
+**Try this:** Edit this file and save it. The browser will live reload instantly!
+:::
+
+### Container Examples
+
+::: card Flexible Structure
+**Organize your way.**
+Create Markdown files in the \`docs/\` folder and map them in \`docmd.config.js\`.
+:::
+
+::: tabs
+== tab "Simple"
+This is a simple tab content.
+
+== tab "Nested"
+::: callout info
+You can even nest other components inside tabs!
+:::
+:::
+
+## 📚 Next Steps
+
+*   [Check the Official Documentation](https://docs.docmd.io)
+*   [Customize your Theme](https://docs.docmd.io/theming)
+*   [Deploy to GitHub Pages](https://docs.docmd.io/deployment)
 `;
 
+const defaultPackageJson = {
+  name: "my-docs",
+  version: "0.0.1",
+  private: true,
+  scripts: {
+    "dev": "docmd dev",
+    "build": "docmd build",
+    "preview": "npx serve site"
+  },
+  dependencies: {
+    "@mgks/docmd": `^${version}`
+  }
+};
+
 async function initProject() {
   const baseDir = process.cwd();
-  const docsDir = path.join(baseDir, 'docs');
+  const packageJsonFile = path.join(baseDir, 'package.json');
   const configFile = path.join(baseDir, 'docmd.config.js');
+  const docsDir = path.join(baseDir, 'docs');
   const indexMdFile = path.join(docsDir, 'index.md');
   const assetsDir = path.join(baseDir, 'assets');
   const assetsCssDir = path.join(assetsDir, 'css');
@@ -169,19 +172,28 @@ async function initProject() {
     assets: false
   };
   
+  // Check if package.json exists
+  if (!await fs.pathExists(packageJsonFile)) {
+    await fs.writeJson(packageJsonFile, defaultPackageJson, { spaces: 2 });
+    console.log('📦 Created `package.json` (Deployment Ready)');
+  } else {
+    console.log('⏭️  Skipped existing `package.json`');
+  }
+
   // Check each file individually
   if (await fs.pathExists(configFile)) {
     existingFiles.push('docmd.config.js');
   }
-  // Check for the config.js as well to warn the user
+
+  // Check for the legacy config.js
   const oldConfigFile = path.join(baseDir, 'config.js');
   if (await fs.pathExists(oldConfigFile)) {
     existingFiles.push('config.js');
   }
   
+  // Check if docs directory exists
   if (await fs.pathExists(docsDir)) {
     dirExists.docs = true;
-    
     if (await fs.pathExists(indexMdFile)) {
       existingFiles.push('docs/index.md');
     }
@@ -234,21 +246,9 @@ async function initProject() {
   } else {
     console.log('📁 Using existing `assets/` directory');
     
-    // Create subdirectories if they don't exist
-    if (!await fs.pathExists(assetsCssDir)) {
-      await fs.ensureDir(assetsCssDir);
-      console.log('📁 Created `assets/css/` directory');
-    }
-    
-    if (!await fs.pathExists(assetsJsDir)) {
-      await fs.ensureDir(assetsJsDir);
-      console.log('📁 Created `assets/js/` directory');
-    }
-    
-    if (!await fs.pathExists(assetsImagesDir)) {
-      await fs.ensureDir(assetsImagesDir);
-      console.log('📁 Created `assets/images/` directory');
-    }
+    if (!await fs.pathExists(assetsCssDir)) await fs.ensureDir(assetsCssDir);
+    if (!await fs.pathExists(assetsJsDir)) await fs.ensureDir(assetsJsDir);
+    if (!await fs.pathExists(assetsImagesDir)) await fs.ensureDir(assetsImagesDir);
   }
   
   // Write config file if it doesn't exist or user confirmed override
@@ -260,7 +260,7 @@ async function initProject() {
   }
   
   // Write index.md file if it doesn't exist or user confirmed override
-  if (!await fs.pathExists(indexMdFile)) {
+  if (!await fs.pathExists(indexMdFile) || shouldOverride) {
     await fs.writeFile(indexMdFile, defaultIndexMdContent, 'utf8');
     console.log('📄 Created `docs/index.md`');
   } else if (shouldOverride) {
@@ -271,6 +271,7 @@ async function initProject() {
   }
   
   console.log('✅ Project initialization complete!');
+  console.log('👉 Run `npm install` to setup dependencies.');
 }
 
 module.exports = { initProject };

package/src/commands/live.js

@@ -0,0 +1,145 @@
+// Source file from the docmd project — https://github.com/docmd-io/docmd
+
+const fs = require('../core/fs-utils'); // Native wrapper
+const path = require('path');
+const esbuild = require('esbuild');
+const { processAssets } = require('../core/asset-manager');
+
+async function build() {
+    console.log('📦 Building @docmd/live core...');
+
+    // Resolve paths relative to src/commands/live.js
+    const SRC_DIR = path.resolve(__dirname, '..'); // Points to /src
+    const LIVE_SRC_DIR = path.join(SRC_DIR, 'live');
+    const DIST_DIR = path.resolve(__dirname, '../../dist'); // Points to /dist in root
+
+    // 1. Clean/Create dist
+    if (await fs.exists(DIST_DIR)) {
+        await fs.remove(DIST_DIR);
+    }
+    await fs.ensureDir(DIST_DIR);
+
+    // 2. Generate Shim for Buffer (Browser compatibility)
+    const shimPath = path.join(LIVE_SRC_DIR, 'shims.js');
+    await fs.writeFile(shimPath, `import { Buffer } from 'buffer'; globalThis.Buffer = Buffer;`);
+
+    // 3. Define the Virtual Template Plugin
+    // This reads EJS files from disk and bundles them as a JSON object string
+    const templatePlugin = {
+        name: 'docmd-templates',
+        setup(build) {
+            build.onResolve({ filter: /^virtual:docmd-templates$/ }, args => ({
+                path: args.path,
+                namespace: 'docmd-templates-ns',
+            }));
+
+            build.onLoad({ filter: /.*/, namespace: 'docmd-templates-ns' }, async () => {
+                const templatesDir = path.join(SRC_DIR, 'templates');
+                const files = await fs.readdir(templatesDir);
+                const templates = {};
+
+                for (const file of files) {
+                    if (file.endsWith('.ejs')) {
+                        const content = await fs.readFile(path.join(templatesDir, file), 'utf8');
+                        templates[file] = content;
+                    }
+                }
+
+                return {
+                    contents: `module.exports = ${JSON.stringify(templates)};`,
+                    loader: 'js',
+                };
+            });
+        },
+    };
+
+    // 4. Define Node Modules Shim Plugin
+    // Stubs out fs/path requires so the browser bundle doesn't crash
+    const nodeShimPlugin = {
+        name: 'node-deps-shim',
+        setup(build) {
+            build.onResolve({ filter: /^(node:)?path$/ }, args => ({ path: args.path, namespace: 'path-shim' }));
+            build.onLoad({ filter: /.*/, namespace: 'path-shim' }, () => ({
+                contents: `
+                    module.exports = {
+                        join: (...args) => args.filter(Boolean).join('/'),
+                        resolve: (...args) => '/' + args.filter(Boolean).join('/'),
+                        basename: (p) => p ? p.split(/[\\\\/]/).pop() : '',
+                        dirname: (p) => p ? p.split(/[\\\\/]/).slice(0, -1).join('/') || '.' : '.',
+                        extname: (p) => { if (!p) return ''; const parts = p.split('.'); return parts.length > 1 ? '.' + parts.pop() : ''; },
+                        isAbsolute: (p) => p.startsWith('/'),
+                        normalize: (p) => p,
+                        sep: '/'
+                    };
+                `,
+                loader: 'js'
+            }));
+
+            build.onResolve({ filter: /^(node:)?fs(\/promises)?|fs-extra$/ }, args => ({ path: args.path, namespace: 'fs-shim' }));
+            build.onLoad({ filter: /.*/, namespace: 'fs-shim' }, () => ({
+                contents: `
+                    module.exports = {
+                        existsSync: () => false,
+                        readFileSync: () => '',
+                        statSync: () => ({ isFile: () => true, isDirectory: () => false }),
+                        constants: { F_OK: 0, R_OK: 4 },
+                        promises: {}
+                    };
+                `, 
+                loader: 'js'
+            }));
+        }
+    };
+
+    // 5. Bundle JS
+    console.log('⚡ Bundling & Compressing JS...');
+    try {
+        await esbuild.build({
+            entryPoints: [path.join(LIVE_SRC_DIR, 'core.js')],
+            bundle: true,
+            outfile: path.join(DIST_DIR, 'docmd-live.js'),
+            platform: 'browser',
+            format: 'iife',
+            globalName: 'docmd',
+            minify: true,
+            define: { 'process.env.NODE_ENV': '"production"' },
+            inject: [shimPath],
+            plugins: [templatePlugin, nodeShimPlugin]
+        });
+
+        // 6. Copy & Minify Static Assets using Universal Manager
+        console.log('📂 Processing static assets...');
+        const assetsSrc = path.join(SRC_DIR, 'assets');
+        const assetsDest = path.join(DIST_DIR, 'assets');
+        
+        if (await fs.exists(assetsSrc)) {
+            await processAssets(assetsSrc, assetsDest, { minify: true });
+        }
+
+        // 7. Copy HTML Wrapper & Minify Live CSS
+        await fs.copy(path.join(LIVE_SRC_DIR, 'index.html'), path.join(DIST_DIR, 'index.html'));
+        
+        const liveCss = await fs.readFile(path.join(LIVE_SRC_DIR, 'live.css'), 'utf8');
+        const minifiedLiveCss = await esbuild.transform(liveCss, { loader: 'css', minify: true });
+        await fs.writeFile(path.join(DIST_DIR, 'live.css'), minifiedLiveCss.code);
+
+        // 8. Copy Favicon to Root
+        const internalFavicon = path.join(assetsSrc, 'favicon.ico');
+        if (await fs.exists(internalFavicon)) {
+            await fs.copy(internalFavicon, path.join(DIST_DIR, 'favicon.ico'));
+        }
+
+        console.log('✅ Live Editor build complete!');
+
+    } catch (e) {
+        console.error('❌ Build failed:', e);
+        process.exit(1);
+    }
+}
+
+// Allow direct execution (via scripts/failsafe.js)
+if (require.main === module) {
+    build();
+}
+
+module.exports = { build };

package/src/core/asset-manager.js

@@ -0,0 +1,72 @@
+// Source file from the docmd project — https://github.com/docmd-io/docmd
+
+const path = require('path');
+const fs = require('./fs-utils');
+const esbuild = require('esbuild');
+
+const DOCMD_HEADER = `/*! Source file from the docmd project — https://github.com/docmd-io/docmd */\n\n`;
+
+/**
+ * Recursively copies assets from src to dest.
+ * Minifies CSS/JS files and adds docmd header.
+ * 
+ * @param {string} srcDir - Source directory
+ * @param {string} destDir - Destination directory
+ * @param {object} options - { minify: boolean }
+ */
+async function processAssets(srcDir, destDir, options = { minify: true }) {
+  // Ensure source exists
+  if (!await fs.exists(srcDir)) return;
+
+  // Ensure dest exists
+  await fs.ensureDir(destDir);
+
+  const entries = await fs.readdir(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await processAssets(srcPath, destPath, options);
+    } else {
+      const ext = path.extname(entry.name).toLowerCase();
+      
+      // Handle CSS & JS: Minify + docmd Header
+      if (ext === '.css' || ext === '.js') {
+        try {
+          const content = await fs.readFile(srcPath, 'utf8');
+          
+          if (options.minify) {
+            // Minify using esbuild
+            const result = await esbuild.transform(content, {
+              loader: ext.slice(1), // 'css' or 'js'
+              minify: true,
+              banner: ext === '.css' || ext === '.js' ? DOCMD_HEADER : ''
+            });
+            await fs.writeFile(destPath, result.code);
+          } else {
+            // Just add banner if not minifying (Dev mode)
+            const contentWithBanner = `${DOCMD_HEADER}\n${content}`;
+            await fs.writeFile(destPath, contentWithBanner);
+          }
+        } catch (e) {
+          console.warn(`⚠️ Processing failed for ${entry.name}, copying original.`);
+          await fs.copy(srcPath, destPath);
+        }
+      } 
+      // Handle HTML Files (if any in assets): HTML Comment Header
+      else if (ext === '.html') {
+        const content = await fs.readFile(srcPath, 'utf8');
+        const htmlBanner = `<!-- Generated by docmd - https://docmd.io -->\n\n`;
+        await fs.writeFile(destPath, htmlBanner + content);
+      }
+      // Everything else (Images, Fonts): Direct Copy
+      else {
+        await fs.copy(srcPath, destPath);
+      }
+    }
+  }
+}
+
+module.exports = { processAssets, DOCMD_HEADER };

package/src/core/config-loader.js

@@ -1,7 +1,7 @@
-// Source file from the docmd project — https://github.com/mgks/docmd
+// Source file from the docmd project — https://github.com/docmd-io/docmd
 
 const path = require('path');
-const fs = require('fs-extra');
+const fs = require('./fs-utils');
 const { validateConfig } = require('./config-validator');
 
 async function loadConfig(configPath) {

package/src/core/config-validator.js

@@ -1,4 +1,4 @@
-// Source file from the docmd project — https://github.com/mgks/docmd
+// Source file from the docmd project — https://github.com/docmd-io/docmd
 
 const chalk = require('chalk');
 

package/src/core/file-processor.js

@@ -1,14 +1,18 @@
-// Source file from the docmd project — https://github.com/mgks/docmd
+// Source file from the docmd project — https://github.com/docmd-io/docmd
 
-const fs = require('fs-extra');
+const fs = require('./fs-utils');
 const path = require('path');
 const matter = require('gray-matter');
 const { createMarkdownItInstance } = require('./markdown/setup');
-const striptags = require('striptags');
 
 function decodeHtmlEntities(html) {
     return html.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, "'").replace(/ /g, ' ');
 }
+
+function stripHtmlTags(str) {
+  if (!str) return '';
+  return str.replace(/<[^>]*>?/gm, '');
+}
   
 function extractHeadingsFromHtml(htmlContent) {
     const headings = [];
@@ -65,12 +69,12 @@ function processMarkdownContent(rawContent, md, config, filePath = 'memory') {
 
     let searchData = null;
     if (!frontmatter.noindex) {
-        const rawText = decodeHtmlEntities(striptags(htmlContent));
-        searchData = {
-            title: frontmatter.title || 'Untitled',
-            content: rawText.slice(0, 5000), // Safety cap to prevent massive JSON
-            headings: headings.map(h => h.text)
-        };
+      const rawText = decodeHtmlEntities(stripHtmlTags(htmlContent));
+      searchData = {
+          title: frontmatter.title || 'Untitled',
+          content: rawText.slice(0, 5000), // Safety cap to prevent massive JSON
+          headings: headings.map(h => h.text)
+      };
     }
   
     return { frontmatter, htmlContent, headings, searchData };

package/src/core/fs-utils.js

@@ -0,0 +1,40 @@
+// Source file from the docmd project — https://github.com/docmd-io/docmd
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function remove(dirPath) {
+  await fs.rm(dirPath, { recursive: true, force: true });
+}
+
+async function copy(src, dest) {
+  await fs.cp(src, dest, { recursive: true });
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeJson(file, object, options = {}) {
+  const content = JSON.stringify(object, null, options.spaces || 2);
+  await fs.writeFile(file, content, 'utf8');
+}
+
+module.exports = {
+  ...fs,
+  ensureDir,
+  remove,
+  copy,
+  pathExists: exists,
+  exists,
+  writeJson
+};