@voltkit/create-volt 0.1.0

package/dist/__tests__/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/index.test.js

@@ -0,0 +1,158 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { __testOnly } from '../index.js';
+const tempDirs = [];
+function createTempDir(prefix) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe('create-volt helpers', () => {
+    it('normalizes valid project names', () => {
+        expect(__testOnly.normalizeProjectName('My App')).toBe('my-app');
+        expect(__testOnly.normalizeProjectName('demo_app')).toBe('demo_app');
+        expect(__testOnly.normalizeProjectName('demo.app')).toBe('demo.app');
+    });
+    it('rejects invalid project names', () => {
+        expect(() => __testOnly.normalizeProjectName('')).toThrow('cannot be empty');
+        expect(() => __testOnly.normalizeProjectName('.')).toThrow('cannot be "." or ".."');
+        expect(() => __testOnly.normalizeProjectName('../bad')).toThrow('single directory segment');
+        expect(() => __testOnly.normalizeProjectName('Bad*Name')).toThrow('must be lowercase');
+    });
+    it('builds human-friendly display names', () => {
+        expect(__testOnly.toDisplayName('my-volt-app')).toBe('My Volt App');
+        expect(__testOnly.toDisplayName('todo_app')).toBe('Todo App');
+    });
+    it('escapes html entities in title content', () => {
+        expect(__testOnly.escapeHtml('<Volt & App>')).toBe('&lt;Volt &amp; App&gt;');
+    });
+    it('updates only top-level name and window.title fields in volt config templates', () => {
+        const input = `
+import { defineConfig } from 'voltkit';
+
+const metadata = {
+  name: 'metadata-name-should-stay',
+  title: 'metadata-title-should-stay',
+};
+
+export default defineConfig({
+  name: 'template-name',
+  version: '0.1.0',
+  window: {
+    title: 'template-title',
+    width: 800,
+    height: 600,
+  },
+  menu: {
+    title: 'menu-title-should-stay',
+  },
+});
+`.trim();
+        const updated = __testOnly.updateVoltConfigContent(input, 'My Demo App');
+        expect(updated).toContain(`name: "My Demo App"`);
+        expect(updated).toContain(`title: "My Demo App"`);
+        expect(updated).toContain(`name: 'metadata-name-should-stay'`);
+        expect(updated).toContain(`title: 'metadata-title-should-stay'`);
+        expect(updated).toContain(`title: 'menu-title-should-stay'`);
+    });
+    it('creates a project from templates and rewrites key files', async () => {
+        const workspaceRoot = createTempDir('create-volt-workspace-');
+        const previousCwd = process.cwd();
+        process.chdir(workspaceRoot);
+        try {
+            await __testOnly.createProject({
+                name: 'my-demo-app',
+                displayName: 'My Demo App',
+                framework: 'vanilla',
+            });
+        }
+        finally {
+            process.chdir(previousCwd);
+        }
+        const targetDir = resolve(workspaceRoot, 'my-demo-app');
+        const packageJson = JSON.parse(readFileSync(resolve(targetDir, 'package.json'), 'utf8'));
+        const config = readFileSync(resolve(targetDir, 'volt.config.ts'), 'utf8');
+        const html = readFileSync(resolve(targetDir, 'index.html'), 'utf8');
+        expect(packageJson.name).toBe('my-demo-app');
+        expect(config).toContain('name: "My Demo App"');
+        expect(config).toContain('title: "My Demo App"');
+        expect(html).toContain('<title>My Demo App</title>');
+    });
+    it('creates an enterprise starter with enterprise packaging defaults', async () => {
+        const workspaceRoot = createTempDir('create-volt-enterprise-workspace-');
+        const previousCwd = process.cwd();
+        process.chdir(workspaceRoot);
+        try {
+            await __testOnly.createProject({
+                name: 'enterprise-demo',
+                displayName: 'Enterprise Demo',
+                framework: 'enterprise',
+            });
+        }
+        finally {
+            process.chdir(previousCwd);
+        }
+        const targetDir = resolve(workspaceRoot, 'enterprise-demo');
+        const packageJson = JSON.parse(readFileSync(resolve(targetDir, 'package.json'), 'utf8'));
+        const config = readFileSync(resolve(targetDir, 'volt.config.ts'), 'utf8');
+        expect(packageJson.name).toBe('enterprise-demo');
+        expect(packageJson.scripts?.doctor).toBe('volt doctor');
+        expect(packageJson.scripts?.package).toBe('volt package');
+        expect(config).toContain('name: "Enterprise Demo"');
+        expect(config).toContain('title: "Enterprise Demo"');
+        expect(config).toContain('package: {');
+        expect(config).toContain("installMode: 'perMachine'");
+        expect(config).toContain('generateAdmx: true');
+    });
+    it('exits with code 1 when target directory already exists', async () => {
+        const workspaceRoot = createTempDir('create-volt-existing-');
+        const previousCwd = process.cwd();
+        mkdirSync(resolve(workspaceRoot, 'my-existing-app'), { recursive: true });
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code) => {
+            const normalized = code === undefined || code === null ? 0 : Number(code);
+            throw new Error(`__PROCESS_EXIT__${normalized}`);
+        }));
+        process.chdir(workspaceRoot);
+        try {
+            await expect(__testOnly.createProject({
+                name: 'my-existing-app',
+                displayName: 'My Existing App',
+                framework: 'vanilla',
+            })).rejects.toThrow('__PROCESS_EXIT__1');
+        }
+        finally {
+            process.chdir(previousCwd);
+            exitSpy.mockRestore();
+        }
+    });
+    it('exits with code 1 when framework template is missing', async () => {
+        const workspaceRoot = createTempDir('create-volt-missing-template-');
+        const previousCwd = process.cwd();
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code) => {
+            const normalized = code === undefined || code === null ? 0 : Number(code);
+            throw new Error(`__PROCESS_EXIT__${normalized}`);
+        }));
+        process.chdir(workspaceRoot);
+        try {
+            await expect(__testOnly.createProject({
+                name: 'bad-template-app',
+                displayName: 'Bad Template App',
+                framework: 'missing-template',
+            })).rejects.toThrow('__PROCESS_EXIT__1');
+        }
+        finally {
+            process.chdir(previousCwd);
+            exitSpy.mockRestore();
+        }
+    });
+});

package/dist/config-updater.d.ts

@@ -0,0 +1 @@
+export declare function updateVoltConfigContent(configContent: string, displayName: string): string;

package/dist/config-updater.js

@@ -0,0 +1,267 @@
+function isIdentifierStart(character) { return /^[A-Za-z_$]$/u.test(character); }
+function isIdentifierPart(character) { return /^[A-Za-z0-9_$]$/u.test(character); }
+function isWhitespace(character) {
+    return character === ' ' || character === '\t' || character === '\n' || character === '\r';
+}
+function skipQuotedString(source, startIndex) {
+    const quote = source[startIndex];
+    let index = startIndex + 1;
+    while (index < source.length) {
+        if (source[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (source[index] === quote) {
+            return index + 1;
+        }
+        index += 1;
+    }
+    return source.length;
+}
+function skipLineComment(source, startIndex) {
+    let index = startIndex + 2;
+    while (index < source.length && source[index] !== '\n') {
+        index += 1;
+    }
+    return index;
+}
+function skipBlockComment(source, startIndex) {
+    let index = startIndex + 2;
+    while (index + 1 < source.length && !(source[index] === '*' && source[index + 1] === '/')) {
+        index += 1;
+    }
+    return Math.min(index + 2, source.length);
+}
+function skipTokenIfStringOrComment(source, startIndex) {
+    const current = source[startIndex];
+    const next = source[startIndex + 1];
+    if (current === '\'' || current === '"' || current === '`') {
+        return skipQuotedString(source, startIndex);
+    }
+    if (current === '/' && next === '/') {
+        return skipLineComment(source, startIndex);
+    }
+    if (current === '/' && next === '*') {
+        return skipBlockComment(source, startIndex);
+    }
+    return null;
+}
+function skipWhitespaceAndComments(source, startIndex) {
+    let index = startIndex;
+    while (index < source.length) {
+        if (isWhitespace(source[index])) {
+            index += 1;
+            continue;
+        }
+        const nextIndex = skipTokenIfStringOrComment(source, index);
+        if (nextIndex === null || nextIndex <= index) {
+            return index;
+        }
+        if (source[index] === '\'' || source[index] === '"' || source[index] === '`') {
+            return index;
+        }
+        index = nextIndex;
+    }
+    return index;
+}
+function findMatchingBrace(source, openBraceIndex) {
+    let depth = 0;
+    let index = openBraceIndex;
+    while (index < source.length) {
+        const nextIndex = skipTokenIfStringOrComment(source, index);
+        if (nextIndex !== null) {
+            index = nextIndex;
+            continue;
+        }
+        if (source[index] === '{') {
+            depth += 1;
+        }
+        else if (source[index] === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                return index;
+            }
+        }
+        index += 1;
+    }
+    return -1;
+}
+function findDefineConfigObjectBounds(source) {
+    const needle = 'defineConfig';
+    let searchStart = 0;
+    while (searchStart < source.length) {
+        const callIndex = source.indexOf(needle, searchStart);
+        if (callIndex === -1) {
+            return null;
+        }
+        let index = skipWhitespaceAndComments(source, callIndex + needle.length);
+        if (source[index] !== '(') {
+            searchStart = callIndex + needle.length;
+            continue;
+        }
+        index = skipWhitespaceAndComments(source, index + 1);
+        if (source[index] !== '{') {
+            searchStart = callIndex + needle.length;
+            continue;
+        }
+        const closeIndex = findMatchingBrace(source, index);
+        return closeIndex === -1 ? null : { start: index, end: closeIndex + 1 };
+    }
+    return null;
+}
+function findPropertyValueEnd(source, valueStart) {
+    let index = valueStart;
+    let curlyDepth = 0;
+    let squareDepth = 0;
+    let parenDepth = 0;
+    while (index < source.length) {
+        const nextIndex = skipTokenIfStringOrComment(source, index);
+        if (nextIndex !== null) {
+            index = nextIndex;
+            continue;
+        }
+        const current = source[index];
+        if (current === '{') {
+            curlyDepth += 1;
+        }
+        else if (current === '}') {
+            if (curlyDepth === 0 && squareDepth === 0 && parenDepth === 0) {
+                return index;
+            }
+            curlyDepth = Math.max(0, curlyDepth - 1);
+        }
+        else if (current === '[') {
+            squareDepth += 1;
+        }
+        else if (current === ']') {
+            squareDepth = Math.max(0, squareDepth - 1);
+        }
+        else if (current === '(') {
+            parenDepth += 1;
+        }
+        else if (current === ')') {
+            parenDepth = Math.max(0, parenDepth - 1);
+        }
+        else if (current === ',' && curlyDepth === 0 && squareDepth === 0 && parenDepth === 0) {
+            return index;
+        }
+        index += 1;
+    }
+    return source.length;
+}
+function parsePropertyAt(source, startIndex) {
+    let index = skipWhitespaceAndComments(source, startIndex);
+    if (index >= source.length) {
+        return null;
+    }
+    let key;
+    if (source[index] === '\'' || source[index] === '"') {
+        const endQuote = skipQuotedString(source, index);
+        if (endQuote <= index + 1 || endQuote > source.length) {
+            return null;
+        }
+        key = source.slice(index + 1, endQuote - 1);
+        index = endQuote;
+    }
+    else if (isIdentifierStart(source[index])) {
+        const keyStart = index;
+        index += 1;
+        while (index < source.length && isIdentifierPart(source[index])) {
+            index += 1;
+        }
+        key = source.slice(keyStart, index);
+    }
+    else {
+        return null;
+    }
+    index = skipWhitespaceAndComments(source, index);
+    if (source[index] !== ':') {
+        return null;
+    }
+    const valueStart = index + 1;
+    return {
+        key,
+        start: valueStart,
+        end: findPropertyValueEnd(source, valueStart),
+    };
+}
+function findTopLevelPropertyValueRange(objectLiteral, propertyName) {
+    let index = 1;
+    let depth = 1;
+    while (index < objectLiteral.length) {
+        const nextIndex = skipTokenIfStringOrComment(objectLiteral, index);
+        if (nextIndex !== null) {
+            index = nextIndex;
+            continue;
+        }
+        if (objectLiteral[index] === '{') {
+            depth += 1;
+            index += 1;
+            continue;
+        }
+        if (objectLiteral[index] === '}') {
+            depth -= 1;
+            index += 1;
+            continue;
+        }
+        if (depth === 1) {
+            const property = parsePropertyAt(objectLiteral, index);
+            if (property) {
+                if (property.key === propertyName) {
+                    return { start: property.start, end: property.end };
+                }
+                index = property.end;
+                continue;
+            }
+        }
+        index += 1;
+    }
+    return null;
+}
+function replacePropertyValue(objectLiteral, propertyName, replacementLiteral) {
+    const propertyRange = findTopLevelPropertyValueRange(objectLiteral, propertyName);
+    if (!propertyRange) {
+        return objectLiteral;
+    }
+    const currentValue = objectLiteral.slice(propertyRange.start, propertyRange.end);
+    const leadingWhitespace = currentValue.match(/^\s*/u)?.[0] ?? '';
+    return (objectLiteral.slice(0, propertyRange.start)
+        + leadingWhitespace
+        + replacementLiteral
+        + objectLiteral.slice(propertyRange.end));
+}
+function replaceWindowTitle(configObject, displayNameLiteral) {
+    const windowRange = findTopLevelPropertyValueRange(configObject, 'window');
+    if (!windowRange) {
+        return configObject;
+    }
+    const windowValue = configObject.slice(windowRange.start, windowRange.end);
+    const objectStart = skipWhitespaceAndComments(windowValue, 0);
+    if (windowValue[objectStart] !== '{') {
+        return configObject;
+    }
+    const objectEnd = findMatchingBrace(windowValue, objectStart);
+    if (objectEnd === -1) {
+        return configObject;
+    }
+    const windowObject = windowValue.slice(objectStart, objectEnd + 1);
+    const updatedWindowObject = replacePropertyValue(windowObject, 'title', displayNameLiteral);
+    const updatedWindowValue = (windowValue.slice(0, objectStart)
+        + updatedWindowObject
+        + windowValue.slice(objectEnd + 1));
+    return (configObject.slice(0, windowRange.start)
+        + updatedWindowValue
+        + configObject.slice(windowRange.end));
+}
+export function updateVoltConfigContent(configContent, displayName) {
+    const configBounds = findDefineConfigObjectBounds(configContent);
+    if (!configBounds) {
+        return configContent;
+    }
+    const displayNameLiteral = JSON.stringify(displayName);
+    const configObject = configContent.slice(configBounds.start, configBounds.end);
+    const updatedConfigObject = replaceWindowTitle(replacePropertyValue(configObject, 'name', displayNameLiteral), displayNameLiteral);
+    return (configContent.slice(0, configBounds.start)
+        + updatedConfigObject
+        + configContent.slice(configBounds.end));
+}

package/dist/create-project.d.ts

@@ -0,0 +1,2 @@
+import { ProjectOptions } from './options.js';
+export declare function createProject(options: ProjectOptions): Promise<void>;

package/dist/create-project.js

@@ -0,0 +1,46 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { updateVoltConfigContent } from './config-updater.js';
+import { escapeHtml } from './options.js';
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+export async function createProject(options) {
+    const targetDir = resolve(process.cwd(), options.name);
+    if (existsSync(targetDir)) {
+        console.error(`  Error: Directory "${options.name}" already exists.`);
+        process.exit(1);
+    }
+    const templateName = `${options.framework}-ts`;
+    const templateDir = resolve(__dirname, 'templates', templateName);
+    if (!existsSync(templateDir)) {
+        console.error(`  Error: Template "${templateName}" not found.`);
+        process.exit(1);
+    }
+    console.log(`  Creating project in ${targetDir}...`);
+    console.log();
+    mkdirSync(targetDir, { recursive: true });
+    cpSync(templateDir, targetDir, { recursive: true });
+    const pkgPath = resolve(targetDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        pkg.name = options.name;
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    }
+    const configPath = resolve(targetDir, 'volt.config.ts');
+    if (existsSync(configPath)) {
+        const config = updateVoltConfigContent(readFileSync(configPath, 'utf-8'), options.displayName);
+        writeFileSync(configPath, config);
+    }
+    const htmlPath = resolve(targetDir, 'index.html');
+    if (existsSync(htmlPath)) {
+        let html = readFileSync(htmlPath, 'utf-8');
+        html = html.replace(/<title>.*?<\/title>/is, `<title>${escapeHtml(options.displayName)}</title>`);
+        writeFileSync(htmlPath, html);
+    }
+    console.log('  Done! Next steps:');
+    console.log();
+    console.log(`  cd ${options.name}`);
+    console.log('  pnpm install');
+    console.log('  pnpm run dev');
+    console.log();
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { updateVoltConfigContent } from './config-updater.js';
+import { createProject } from './create-project.js';
+import { escapeHtml, normalizeProjectName, toDisplayName } from './options.js';
+export declare const __testOnly: {
+    normalizeProjectName: typeof normalizeProjectName;
+    toDisplayName: typeof toDisplayName;
+    escapeHtml: typeof escapeHtml;
+    updateVoltConfigContent: typeof updateVoltConfigContent;
+    createProject: typeof createProject;
+};

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import prompts from 'prompts';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { updateVoltConfigContent } from './config-updater.js';
+import { createProject } from './create-project.js';
+import { escapeHtml, normalizeProjectName, toDisplayName } from './options.js';
+async function main() {
+    const argName = process.argv[2];
+    console.log();
+    console.log('  Volt - Lightweight Desktop App Framework');
+    console.log();
+    const response = await prompts([
+        {
+            type: argName ? null : 'text',
+            name: 'name',
+            message: 'Project name:',
+            initial: 'my-volt-app',
+        },
+        {
+            type: 'select',
+            name: 'framework',
+            message: 'Select a framework:',
+            choices: [
+                { title: 'Vanilla', value: 'vanilla', description: 'Plain HTML/CSS/TypeScript' },
+                { title: 'React', value: 'react', description: 'React 19 + TypeScript' },
+                { title: 'Svelte', value: 'svelte', description: 'Svelte 5 + TypeScript' },
+                { title: 'Vue', value: 'vue', description: 'Vue 3 + TypeScript' },
+                { title: 'Enterprise', value: 'enterprise', description: 'Vanilla + enterprise-ready packaging defaults' },
+            ],
+        },
+    ], {
+        onCancel: () => {
+            console.log('Cancelled.');
+            process.exit(0);
+        },
+    });
+    const projectName = normalizeProjectName(String(argName ?? response.name ?? ''));
+    const options = {
+        name: projectName,
+        displayName: toDisplayName(projectName),
+        framework: response.framework ?? 'vanilla',
+    };
+    await createProject(options);
+}
+export const __testOnly = {
+    normalizeProjectName,
+    toDisplayName,
+    escapeHtml,
+    updateVoltConfigContent,
+    createProject,
+};
+const isEntrypoint = (() => {
+    const argvPath = process.argv[1];
+    if (!argvPath) {
+        return false;
+    }
+    return resolve(argvPath) === fileURLToPath(import.meta.url);
+})();
+if (isEntrypoint) {
+    main().catch((error) => {
+        console.error(error);
+        process.exitCode = 1;
+    });
+}

package/dist/options.d.ts

@@ -0,0 +1,8 @@
+export interface ProjectOptions {
+    name: string;
+    displayName: string;
+    framework: 'vanilla' | 'react' | 'svelte' | 'vue' | 'enterprise';
+}
+export declare function normalizeProjectName(input: string): string;
+export declare function toDisplayName(projectName: string): string;
+export declare function escapeHtml(value: string): string;

package/dist/options.js

@@ -0,0 +1,32 @@
+import { isAbsolute } from 'node:path';
+const PROJECT_NAME_RE = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/;
+export function normalizeProjectName(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error('Project name cannot be empty.');
+    }
+    if (trimmed === '.' || trimmed === '..') {
+        throw new Error('Project name cannot be "." or "..".');
+    }
+    if (isAbsolute(trimmed) || trimmed.includes('/') || trimmed.includes('\\')) {
+        throw new Error('Project name must be a single directory segment, not a path.');
+    }
+    const normalized = trimmed.toLowerCase().replace(/\s+/g, '-');
+    if (!PROJECT_NAME_RE.test(normalized)) {
+        throw new Error('Project name must be lowercase and use letters, numbers, ".", "_" or "-".');
+    }
+    return normalized;
+}
+export function toDisplayName(projectName) {
+    const parts = projectName.split(/[-_]+/).filter(Boolean);
+    if (parts.length === 0) {
+        return 'Volt App';
+    }
+    return parts.map((part) => part[0].toUpperCase() + part.slice(1)).join(' ');
+}
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}

package/dist/templates/enterprise-ts/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My Volt App</title>
+  <link rel="stylesheet" href="/src/style.css">
+</head>
+<body>
+  <div id="app">
+    <h1>Volt Enterprise Starter</h1>
+    <p>Baseline scaffold with enterprise packaging defaults.</p>
+    <button id="counter" type="button">Count: 0</button>
+  </div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>

package/dist/templates/enterprise-ts/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "my-volt-app",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "volt dev",
+    "build": "volt build",
+    "preview": "volt preview",
+    "doctor": "volt doctor",
+    "package": "volt package",
+    "package:msix": "volt package --target win32 --format msix"
+  },
+  "dependencies": {
+    "voltkit": "^0.1.0"
+  },
+  "devDependencies": {
+    "@voltkit/volt-cli": "^0.1.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}

package/dist/templates/enterprise-ts/src/backend.ts

@@ -0,0 +1,3 @@
+import { ipcMain } from 'volt:ipc';
+
+ipcMain.handle('app:ping', () => ({ ok: true }));

package/dist/templates/enterprise-ts/src/main.ts

@@ -0,0 +1,9 @@
+let count = 0;
+
+const button = document.getElementById('counter')!;
+button.addEventListener('click', () => {
+  count++;
+  button.textContent = `Count: ${count}`;
+});
+
+console.log('Volt enterprise starter is running.');