specweave 0.12.6 → 0.13.0

package/dist/src/utils/docs-preview/sidebar-builder.js

@@ -0,0 +1,202 @@
+/**
+ * Sidebar builder for Docusaurus
+ * Automatically generates sidebar.js from .specweave/docs/ folder structure
+ */
+import * as path from 'path';
+import * as fs from 'fs-extra';
+/**
+ * Priority order for top-level folders
+ * Lower number = appears first in sidebar
+ */
+const FOLDER_PRIORITY = {
+    strategy: 1,
+    specs: 2,
+    architecture: 3,
+    delivery: 4,
+    operations: 5,
+    governance: 6,
+    projects: 7 // Multi-project support
+};
+/**
+ * Default folders to exclude from sidebar
+ */
+const DEFAULT_EXCLUDE_FOLDERS = [
+    'node_modules',
+    '.git',
+    '.DS_Store',
+    'legacy' // Brownfield imports (temporary, not for display)
+];
+/**
+ * Build sidebar from folder structure
+ */
+export async function buildSidebar(options) {
+    const { docsPath, excludeFolders = DEFAULT_EXCLUDE_FOLDERS, maxDepth = 5 } = options;
+    // Check if docs path exists
+    if (!await fs.pathExists(docsPath)) {
+        throw new Error(`Documentation path does not exist: ${docsPath}`);
+    }
+    // Scan folders and build sidebar items
+    const items = await scanFolder(docsPath, docsPath, excludeFolders, 0, maxDepth);
+    // Sort by priority (strategy first, governance last)
+    const sortedItems = sortByPriority(items);
+    return {
+        docs: sortedItems
+    };
+}
+/**
+ * Scan folder recursively and build sidebar items
+ */
+async function scanFolder(basePath, currentPath, excludeFolders, depth, maxDepth) {
+    if (depth >= maxDepth) {
+        return [];
+    }
+    const items = [];
+    try {
+        const entries = await fs.readdir(currentPath, { withFileTypes: true });
+        // Separate folders and files
+        const folders = entries.filter(e => e.isDirectory() && !excludeFolders.includes(e.name));
+        const files = entries.filter(e => e.isFile() && e.name.endsWith('.md'));
+        // Process folders first (categories)
+        for (const folder of folders) {
+            const folderPath = path.join(currentPath, folder.name);
+            const childItems = await scanFolder(basePath, folderPath, excludeFolders, depth + 1, maxDepth);
+            if (childItems.length > 0) {
+                items.push({
+                    type: 'category',
+                    label: formatLabel(folder.name),
+                    items: childItems
+                });
+            }
+        }
+        // Process markdown files (docs)
+        for (const file of files) {
+            const relativePath = path.relative(basePath, path.join(currentPath, file.name));
+            const docId = relativePath.replace(/\.md$/, '').replace(/\\/g, '/');
+            items.push({
+                type: 'doc',
+                id: docId
+            });
+        }
+        return items;
+    }
+    catch (error) {
+        console.error(`Error scanning folder ${currentPath}:`, error);
+        return [];
+    }
+}
+/**
+ * Sort sidebar items by priority
+ */
+function sortByPriority(items) {
+    return items.sort((a, b) => {
+        // Extract folder name from label
+        const aFolder = a.label?.toLowerCase().replace(/\s+/g, '-') || '';
+        const bFolder = b.label?.toLowerCase().replace(/\s+/g, '-') || '';
+        // Get priorities (default to 999 if not found)
+        const aPriority = FOLDER_PRIORITY[aFolder] || 999;
+        const bPriority = FOLDER_PRIORITY[bFolder] || 999;
+        // Sort by priority
+        if (aPriority !== bPriority) {
+            return aPriority - bPriority;
+        }
+        // If same priority, sort alphabetically
+        return aFolder.localeCompare(bFolder);
+    });
+}
+/**
+ * Format folder name to human-readable label
+ * Examples:
+ * - "strategy" → "Strategy"
+ * - "architecture" → "Architecture"
+ * - "adr" → "ADRs"
+ * - "my-feature-spec" → "My Feature Spec"
+ */
+function formatLabel(folderName) {
+    // Special cases
+    const specialCases = {
+        adr: 'ADRs',
+        adrs: 'ADRs',
+        hld: 'HLD',
+        lld: 'LLD',
+        prd: 'PRDs',
+        okr: 'OKRs',
+        api: 'API',
+        cli: 'CLI',
+        ui: 'UI',
+        ux: 'UX',
+        sre: 'SRE',
+        devops: 'DevOps',
+        mlops: 'MLOps',
+        k8s: 'Kubernetes'
+    };
+    const normalized = folderName.toLowerCase();
+    if (specialCases[normalized]) {
+        return specialCases[normalized];
+    }
+    // Convert kebab-case or snake_case to Title Case
+    return folderName
+        .replace(/[-_]/g, ' ')
+        .split(' ')
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join(' ');
+}
+/**
+ * Generate sidebars.js content as string
+ */
+export function generateSidebarsJS(sidebar) {
+    return `/**
+ * Auto-generated sidebar for SpecWeave documentation
+ * Generated: ${new Date().toISOString()}
+ *
+ * DO NOT EDIT THIS FILE MANUALLY
+ * Regenerate with: /specweave:docs preview
+ */
+
+module.exports = ${JSON.stringify(sidebar, null, 2)};
+`;
+}
+/**
+ * Write sidebar to file
+ */
+export async function writeSidebar(filePath, sidebar) {
+    const content = generateSidebarsJS(sidebar);
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Count total documents in sidebar
+ */
+export function countDocuments(sidebar) {
+    let count = 0;
+    function traverse(items) {
+        for (const item of items) {
+            if (item.type === 'doc') {
+                count++;
+            }
+            else if (item.type === 'category' && item.items) {
+                traverse(item.items);
+            }
+        }
+    }
+    traverse(sidebar.docs);
+    return count;
+}
+/**
+ * Count total categories in sidebar
+ */
+export function countCategories(sidebar) {
+    let count = 0;
+    function traverse(items) {
+        for (const item of items) {
+            if (item.type === 'category') {
+                count++;
+                if (item.items) {
+                    traverse(item.items);
+                }
+            }
+        }
+    }
+    traverse(sidebar.docs);
+    return count;
+}
+//# sourceMappingURL=sidebar-builder.js.map

package/dist/src/utils/docs-preview/sidebar-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidebar-builder.js","sourceRoot":"","sources":["../../../../src/utils/docs-preview/sidebar-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,UAAU,CAAC;AAG/B;;;GAGG;AACH,MAAM,eAAe,GAA2B;IAC9C,QAAQ,EAAE,CAAC;IACX,KAAK,EAAE,CAAC;IACR,YAAY,EAAE,CAAC;IACf,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC,CAAC,wBAAwB;CACrC,CAAC;AAEF;;GAEG;AACH,MAAM,uBAAuB,GAAG;IAC9B,cAAc;IACd,MAAM;IACN,WAAW;IACX,QAAQ,CAAC,kDAAkD;CAC5D,CAAC;AAQF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAA4B;IAC7D,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,uBAAuB,EAAE,QAAQ,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IAErF,4BAA4B;IAC5B,IAAI,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,uCAAuC;IACvC,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IAEhF,qDAAqD;IACrD,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAE1C,OAAO;QACL,IAAI,EAAE,WAAW;KAClB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,UAAU,CACvB,QAAgB,EAChB,WAAmB,EACnB,cAAwB,EACxB,KAAa,EACb,QAAgB;IAEhB,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAkB,EAAE,CAAC;IAEhC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAEvE,6BAA6B;QAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACzF,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAExE,qCAAqC;QACrC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YACvD,MAAM,UAAU,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;YAE/F,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,KAAK,CAAC,IAAI,CAAC;oBACT,IAAI,EAAE,UAAU;oBAChB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC;oBAC/B,KAAK,EAAE,UAAU;iBAClB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,gCAAgC;QAChC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YAChF,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAEpE,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,KAAK;gBACX,EAAE,EAAE,KAAK;aACV,CAAC,CAAC;QACL,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,yBAAyB,WAAW,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9D,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,KAAoB;IAC1C,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACzB,iCAAiC;QACjC,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QAClE,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QAElE,+CAA+C;QAC/C,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC;QAClD,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC;QAElD,mBAAmB;QACnB,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,SAAS,GAAG,SAAS,CAAC;QAC/B,CAAC;QAED,wCAAwC;QACxC,OAAO,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,UAAkB;IACrC,gBAAgB;IAChB,MAAM,YAAY,GAA2B;QAC3C,GAAG,EAAE,MAAM;QACX,IAAI,EAAE,MAAM;QACZ,GAAG,EAAE,KAAK;QACV,GAAG,EAAE,KAAK;QACV,GAAG,EAAE,MAAM;QACX,GAAG,EAAE,MAAM;QACX,GAAG,EAAE,KAAK;QACV,GAAG,EAAE,KAAK;QACV,EAAE,EAAE,IAAI;QACR,EAAE,EAAE,IAAI;QACR,GAAG,EAAE,KAAK;QACV,MAAM,EAAE,QAAQ;QAChB,KAAK,EAAE,OAAO;QACd,GAAG,EAAE,YAAY;KAClB,CAAC;IAEF,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7B,OAAO,YAAY,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAED,iDAAiD;IACjD,OAAO,UAAU;SACd,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SACvE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,OAAO;;gBAEO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;;;;;;mBAMrB,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;CAClD,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB,EAAE,OAAgB;IACnE,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3C,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,SAAS,QAAQ,CAAC,KAAoB;QACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;gBACxB,KAAK,EAAE,CAAC;YACV,CAAC;iBAAM,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAClD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,SAAS,QAAQ,CAAC,KAAoB;QACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC7B,KAAK,EAAE,CAAC;gBACR,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;oBACf,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACvB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/utils/docs-preview/types.d.ts

@@ -0,0 +1,57 @@
+export interface DocusaurusConfig {
+    title: string;
+    tagline: string;
+    url: string;
+    baseUrl: string;
+    docsPath: string;
+    port?: number;
+    theme?: 'default' | 'classic' | 'dark';
+    excludeFolders?: string[];
+}
+export interface SidebarItem {
+    type: 'doc' | 'category';
+    label?: string;
+    id?: string;
+    items?: SidebarItem[];
+}
+export interface Sidebar {
+    docs: SidebarItem[];
+}
+export interface SetupOptions {
+    projectRoot: string;
+    targetDir: string;
+    docsPath: string;
+    config: DocusaurusConfig;
+    force?: boolean;
+}
+export interface ServerOptions {
+    port: number;
+    openBrowser: boolean;
+    host?: string;
+}
+export interface InstallOptions {
+    targetDir: string;
+    packages: string[];
+    dev?: boolean;
+}
+export interface NodeVersion {
+    version: string;
+    major: number;
+    minor: number;
+    patch: number;
+    compatible: boolean;
+}
+export interface BuildResult {
+    success: boolean;
+    outputPath: string;
+    size: number;
+    duration: number;
+    errors?: string[];
+}
+export interface ServerProcess {
+    pid: number;
+    port: number;
+    url: string;
+    stop: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/utils/docs-preview/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/utils/docs-preview/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,WAAW,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/src/utils/docs-preview/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/utils/docs-preview/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/utils/docs-preview/types.ts"],"names":[],"mappings":""}

package/dist/src/utils/env-file.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Environment File Utilities
+ *
+ * Parse, update, and validate .env files
+ *
+ * @module utils/env-file
+ */
+export interface EnvVariable {
+    key: string;
+    value: string;
+}
+/**
+ * Parse .env file content into key-value pairs
+ *
+ * @param content - Content of .env file
+ * @returns Record of key-value pairs
+ */
+export declare function parseEnvFile(content: string): Record<string, string>;
+/**
+ * Update or add environment variable in .env content
+ *
+ * @param envContent - Current .env file content
+ * @param key - Environment variable key
+ * @param value - Environment variable value
+ * @returns Updated .env content
+ */
+export declare function updateEnvVar(envContent: string, key: string, value: string): string;
+/**
+ * Update multiple environment variables
+ *
+ * @param envContent - Current .env file content
+ * @param vars - Array of environment variables to update
+ * @returns Updated .env content
+ */
+export declare function updateEnvVars(envContent: string, vars: EnvVariable[]): string;
+/**
+ * Read .env file from project directory
+ *
+ * @param projectPath - Path to project root
+ * @returns Content of .env file, or empty string if not found
+ */
+export declare function readEnvFile(projectPath: string): string;
+/**
+ * Write .env file to project directory
+ *
+ * @param projectPath - Path to project root
+ * @param content - Content to write
+ */
+export declare function writeEnvFile(projectPath: string, content: string): void;
+/**
+ * Create .env file from .env.example template
+ *
+ * @param projectPath - Path to project root
+ * @returns Content of .env file (from template or empty)
+ */
+export declare function createEnvFromTemplate(projectPath: string): string;
+/**
+ * Verify .env is in .gitignore
+ *
+ * @param projectPath - Path to project root
+ * @returns True if .env is gitignored, false otherwise
+ */
+export declare function isEnvGitignored(projectPath: string): boolean;
+/**
+ * Add .env to .gitignore if not already present
+ *
+ * @param projectPath - Path to project root
+ */
+export declare function ensureEnvGitignored(projectPath: string): void;
+/**
+ * Validate required environment variables are present
+ *
+ * @param envContent - Content of .env file
+ * @param requiredKeys - Array of required keys
+ * @returns Object with validation result and missing keys
+ */
+export declare function validateEnvVars(envContent: string, requiredKeys: string[]): {
+    valid: boolean;
+    missing: string[];
+};
+/**
+ * Check if .env file exists in project
+ *
+ * @param projectPath - Path to project root
+ * @returns True if .env exists, false otherwise
+ */
+export declare function envFileExists(projectPath: string): boolean;
+//# sourceMappingURL=env-file.d.ts.map

package/dist/src/utils/env-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-file.d.ts","sourceRoot":"","sources":["../../../src/utils/env-file.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAWnF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,WAAW,EAAE,GAClB,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAcvE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQjE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAS5D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAe7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAcvC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAG1D"}

package/dist/src/utils/env-file.js

@@ -0,0 +1,180 @@
+/**
+ * Environment File Utilities
+ *
+ * Parse, update, and validate .env files
+ *
+ * @module utils/env-file
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Parse .env file content into key-value pairs
+ *
+ * @param content - Content of .env file
+ * @returns Record of key-value pairs
+ */
+export function parseEnvFile(content) {
+    const result = {};
+    const lines = content.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip empty lines and comments
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        // Parse KEY=VALUE
+        const equalsIndex = trimmed.indexOf('=');
+        if (equalsIndex > 0) {
+            const key = trimmed.substring(0, equalsIndex).trim();
+            const value = trimmed.substring(equalsIndex + 1).trim();
+            // Remove quotes if present
+            const unquotedValue = value.replace(/^["']|["']$/g, '');
+            result[key] = unquotedValue;
+        }
+    }
+    return result;
+}
+/**
+ * Update or add environment variable in .env content
+ *
+ * @param envContent - Current .env file content
+ * @param key - Environment variable key
+ * @param value - Environment variable value
+ * @returns Updated .env content
+ */
+export function updateEnvVar(envContent, key, value) {
+    const regex = new RegExp(`^${key}=.*$`, 'm');
+    if (regex.test(envContent)) {
+        // Update existing variable
+        return envContent.replace(regex, `${key}=${value}`);
+    }
+    else {
+        // Add new variable (append)
+        const trimmed = envContent.trim();
+        return trimmed ? `${trimmed}\n${key}=${value}\n` : `${key}=${value}\n`;
+    }
+}
+/**
+ * Update multiple environment variables
+ *
+ * @param envContent - Current .env file content
+ * @param vars - Array of environment variables to update
+ * @returns Updated .env content
+ */
+export function updateEnvVars(envContent, vars) {
+    let result = envContent;
+    for (const { key, value } of vars) {
+        result = updateEnvVar(result, key, value);
+    }
+    return result;
+}
+/**
+ * Read .env file from project directory
+ *
+ * @param projectPath - Path to project root
+ * @returns Content of .env file, or empty string if not found
+ */
+export function readEnvFile(projectPath) {
+    const envPath = path.join(projectPath, '.env');
+    if (fs.existsSync(envPath)) {
+        return fs.readFileSync(envPath, 'utf-8');
+    }
+    return '';
+}
+/**
+ * Write .env file to project directory
+ *
+ * @param projectPath - Path to project root
+ * @param content - Content to write
+ */
+export function writeEnvFile(projectPath, content) {
+    const envPath = path.join(projectPath, '.env');
+    fs.writeFileSync(envPath, content, 'utf-8');
+    // Set user-only read/write permissions (0o600) for security
+    // This prevents other users on the system from reading sensitive credentials
+    try {
+        fs.chmodSync(envPath, 0o600);
+    }
+    catch (error) {
+        // Non-critical error - log but continue (Windows doesn't support chmod)
+        if (process.env.DEBUG) {
+            console.error(`Warning: Could not set .env permissions: ${error}`);
+        }
+    }
+}
+/**
+ * Create .env file from .env.example template
+ *
+ * @param projectPath - Path to project root
+ * @returns Content of .env file (from template or empty)
+ */
+export function createEnvFromTemplate(projectPath) {
+    const envExamplePath = path.join(projectPath, '.env.example');
+    if (fs.existsSync(envExamplePath)) {
+        return fs.readFileSync(envExamplePath, 'utf-8');
+    }
+    return '';
+}
+/**
+ * Verify .env is in .gitignore
+ *
+ * @param projectPath - Path to project root
+ * @returns True if .env is gitignored, false otherwise
+ */
+export function isEnvGitignored(projectPath) {
+    const gitignorePath = path.join(projectPath, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        return false;
+    }
+    const gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
+    return gitignoreContent.includes('.env');
+}
+/**
+ * Add .env to .gitignore if not already present
+ *
+ * @param projectPath - Path to project root
+ */
+export function ensureEnvGitignored(projectPath) {
+    const gitignorePath = path.join(projectPath, '.gitignore');
+    if (!isEnvGitignored(projectPath)) {
+        // Append .env to .gitignore
+        const existingContent = fs.existsSync(gitignorePath)
+            ? fs.readFileSync(gitignorePath, 'utf-8')
+            : '';
+        const updatedContent = existingContent.trim()
+            ? `${existingContent}\n.env\n`
+            : '.env\n';
+        fs.writeFileSync(gitignorePath, updatedContent, 'utf-8');
+    }
+}
+/**
+ * Validate required environment variables are present
+ *
+ * @param envContent - Content of .env file
+ * @param requiredKeys - Array of required keys
+ * @returns Object with validation result and missing keys
+ */
+export function validateEnvVars(envContent, requiredKeys) {
+    const parsed = parseEnvFile(envContent);
+    const missing = [];
+    for (const key of requiredKeys) {
+        if (!parsed[key] || parsed[key].trim() === '') {
+            missing.push(key);
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing
+    };
+}
+/**
+ * Check if .env file exists in project
+ *
+ * @param projectPath - Path to project root
+ * @returns True if .env exists, false otherwise
+ */
+export function envFileExists(projectPath) {
+    const envPath = path.join(projectPath, '.env');
+    return fs.existsSync(envPath);
+}
+//# sourceMappingURL=env-file.js.map

package/dist/src/utils/env-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-file.js","sourceRoot":"","sources":["../../../src/utils/env-file.ts"],"names":[],"mappings":"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"}