@swell/cli 2.9.17 → 2.9.19

package/dist/help/custom-help.js

@@ -1,4 +1,5 @@
 import { Help } from '@oclif/core';
+import { FRONTEND_HOSTING_LABELS, FRONTEND_TEMPLATES, } from '../lib/apps/frontend-templates.js';
 /**
  * Custom Help class for Swell CLI
  *
@@ -79,6 +80,21 @@ export default class CustomHelp extends Help {
         if (flagsSection.length > 0) {
             lines.push('', ...flagsSection);
         }
+        if (helpMeta.frontendTemplates) {
+            lines.push('', 'FRONTENDS  --frontend <template>', '', `  ${FRONTEND_HOSTING_LABELS.managed}`);
+            for (const template of FRONTEND_TEMPLATES.filter((item) => item.hosting === 'managed')) {
+                const detail = template.appTypes
+                    ? `${template.appTypes.join(', ')} apps only`
+                    : template.description;
+                lines.push(`    ${template.slug.padEnd(15)}${template.name} · ${detail}`);
+            }
+            lines.push('', `  ${FRONTEND_HOSTING_LABELS['self-hosted']}`);
+            const slugs = FRONTEND_TEMPLATES.filter((item) => item.hosting === 'self-hosted').map((item) => item.slug);
+            lines.push(`    ${slugs.join(', ')}`);
+            if (helpMeta.frontendTemplates === 'optional') {
+                lines.push('', '  Skip frontend setup', '    none (default with -y)');
+            }
+        }
         // DESCRIPTION section (if description differs from summary)
         const descSection = this.formatDescriptionSection(command);
         if (descSection.length > 0) {
@@ -257,13 +273,18 @@ export default class CustomHelp extends Help {
             // Alphabetical
             return aName.localeCompare(bName);
         });
-        for (const [name, flag] of flagEntries) {
+        const flagLabels = new Map(Object.entries(command.flags)
+            .filter(([name, flag]) => name !== 'help' && !flag.hidden)
+            .map(([name, flag]) => {
             const shortChar = flag.char ? `-${flag.char}, ` : '    ';
-            const longFlag = `--${name}`;
-            const isBoolean = flag.type === 'boolean';
-            const hasOptions = 'options' in flag && flag.options;
-            const valueStr = isBoolean ? '' : hasOptions ? '=<option>' : '=<value>';
-            const flagStr = `${shortChar}${longFlag}${valueStr}`;
+            const value = ('helpValue' in flag && flag.helpValue) ||
+                ('options' in flag && flag.options ? 'option' : 'value');
+            const suffix = flag.type === 'boolean' ? '' : `=<${value}>`;
+            return [name, `${shortChar}--${name}${suffix}`];
+        }));
+        const flagWidth = Math.max(30, ...[...flagLabels.values()].map((label) => label.length));
+        for (const [name, flag] of flagEntries) {
+            const flagStr = flagLabels.get(name);
             // Get description, clean up redundant "(required in -y)" text
             let desc = flag.summary || flag.description || '';
             desc = desc
@@ -272,7 +293,7 @@ export default class CustomHelp extends Help {
                 .replaceAll(/\s*\(default in -y: .+\)/gi, '')
                 .split('\n')[0]
                 .trim();
-            lines.push(`  ${flagStr.padEnd(30)} ${desc}`);
+            lines.push(`  ${flagStr.padEnd(flagWidth)} ${desc}`);
         }
         return lines;
     }

package/dist/help/types.d.ts

@@ -31,6 +31,8 @@ export interface VariantOption {
  * Add this as a static property on commands that need enhanced help output.
  */
 export interface HelpMeta {
+    /** Show the public frontend template choices grouped by hosting mode. */
+    frontendTemplates?: 'optional' | 'required';
     /**
      * Custom usage line for direct/non-interactive mode.
      * Example: '<id> -t <type> [...] -y'

package/dist/lib/app-config.js

@@ -8,6 +8,12 @@ const schema = {
     compatibilities: { type: 'object' },
     description: { type: 'string' },
     extensions: { type: 'array' },
+    frontend: {
+        type: 'object',
+        properties: {
+            hosting: { type: 'string', enum: ['managed', 'self-hosted'] },
+        },
+    },
     id: { type: 'string' },
     integrations: { type: 'array' },
     name: { type: 'string' },

package/dist/lib/apps/frontend-package.d.ts

@@ -0,0 +1,36 @@
+export type ManagedFrontendFramework = 'react' | 'vinext';
+export interface FrontendPackageFile {
+    kind: 'module' | 'asset';
+    path: string;
+    content_type: string;
+    size: number;
+    sha256: string;
+    data: string;
+}
+export interface FrontendPackage {
+    format: 1;
+    framework: ManagedFrontendFramework;
+    entrypoint: string;
+    runtime: {
+        bindings: string[];
+        cache: boolean;
+        compatibility_date: string;
+        compatibility_flags: string[];
+    };
+    assets: {
+        _headers?: string;
+        _redirects?: string;
+        html_handling: 'auto-trailing-slash' | 'none';
+        not_found_handling: 'none' | 'single-page-application';
+        run_worker_first: boolean;
+    };
+    files: FrontendPackageFile[];
+    digest: string;
+}
+export declare function frontendPackageDigest(pkg: FrontendPackage): string;
+export declare function isPrivateFrontendAsset(name: string): boolean;
+export declare function verifyFrontendPackage(pkg: FrontendPackage): void;
+export declare function checkModuleGraph(pkg: FrontendPackage): Promise<void>;
+export declare function captureFrontendPackage(frontend: string, framework: ManagedFrontendFramework): Promise<FrontendPackage>;
+export declare function buildFrontendPackage(frontend: string, framework: ManagedFrontendFramework): Promise<FrontendPackage>;
+export declare function getManagedFrontendFramework(frontend: string): Promise<ManagedFrontendFramework>;

package/dist/lib/apps/frontend-package.js

@@ -0,0 +1,375 @@
+import { build } from 'esbuild';
+import { execa } from 'execa';
+import { isIgnoredByIgnoreFiles } from 'globby';
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import * as os from 'node:os';
+import * as path from 'node:path';
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function compareFiles(a, b) {
+    const first = `${a.kind}/${a.path}`;
+    const second = `${b.kind}/${b.path}`;
+    return first < second ? -1 : first > second ? 1 : 0;
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonical(item)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value)
+            .filter((key) => value[key] !== undefined)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+// Hash the serving contract and sorted file descriptors, independently of encoding.
+export function frontendPackageDigest(pkg) {
+    const { files, ...settings } = pkg;
+    const manifest = { ...settings, digest: undefined };
+    return sha256(canonical({
+        ...manifest,
+        files: [...files]
+            .sort(compareFiles)
+            .map(({ data: _data, ...file }) => file),
+    }));
+}
+function checkPath(name) {
+    if (!name ||
+        // eslint-disable-next-line no-control-regex
+        /[\u0000-\u001F#%?\\]/.test(name) ||
+        name.split('/').some((part) => !part || part === '.' || part === '..')) {
+        throw new Error(`Invalid frontend package path: ${name}`);
+    }
+}
+// Mandatory exclusions apply even when .assetsignore tries to re-include them.
+export function isPrivateFrontendAsset(name) {
+    return name
+        .split('/')
+        .some((part) => (part.startsWith('.') && part !== '.well-known') ||
+        part === 'node_modules' ||
+        part.endsWith('.map') ||
+        /^(?:wrangler(?:\.[^.]+)?\.(?:jsonc?|toml)|(?:vite|vitest|next|eslint|postcss|tailwind)\.config\.[cm]?[jt]s|(?:tsconfig|jsconfig)(?:\.[^.]+)?\.json)$/.test(part) ||
+        /^(?:package(?:-lock)?\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|_headers|_redirects|_worker\.js)$/.test(part));
+}
+function packageFile(kind, name, contentType, bytes) {
+    checkPath(name);
+    return {
+        kind,
+        path: name,
+        content_type: contentType,
+        size: bytes.length,
+        sha256: sha256(bytes),
+        data: bytes.toString('base64'),
+    };
+}
+// Local integrity check; platform admission must independently validate untrusted input.
+export function verifyFrontendPackage(pkg) {
+    const names = new Set();
+    for (const file of pkg.files) {
+        checkPath(file.path);
+        if (file.kind === 'module' && file.path === 'metadata') {
+            throw new Error('metadata is a reserved Worker module name');
+        }
+        const key = `${file.kind}/${file.path}`;
+        if (names.has(key))
+            throw new Error(`Duplicate frontend file: ${key}`);
+        names.add(key);
+        const bytes = Buffer.from(file.data, 'base64');
+        if (bytes.toString('base64') !== file.data ||
+            bytes.length !== file.size ||
+            sha256(bytes) !== file.sha256) {
+            throw new Error(`Frontend file integrity mismatch: ${key}`);
+        }
+        if (file.kind === 'asset' && isPrivateFrontendAsset(file.path)) {
+            throw new Error(`Private frontend asset: ${file.path}`);
+        }
+    }
+    if (!names.has(`module/${pkg.entrypoint}`)) {
+        throw new Error('Frontend package is missing its Worker entrypoint');
+    }
+    if (pkg.framework === 'react' && !names.has('asset/index.html')) {
+        throw new Error('React frontend package is missing index.html');
+    }
+    if (frontendPackageDigest(pkg) !== pkg.digest) {
+        throw new Error('Frontend package digest mismatch (missing files or changed settings)');
+    }
+}
+async function collectAssets(directory) {
+    const ignored = await isIgnoredByIgnoreFiles('.assetsignore', {
+        cwd: directory,
+    });
+    const files = [];
+    async function walk(relative = '') {
+        for (const entry of await fs.readdir(path.join(directory, relative), {
+            withFileTypes: true,
+        })) {
+            const name = path.posix.join(relative, entry.name);
+            if (isPrivateFrontendAsset(name) || ignored(name))
+                continue;
+            if (entry.isDirectory()) {
+                // eslint-disable-next-line no-await-in-loop
+                await walk(name);
+            }
+            else if (entry.isFile()) {
+                // Asset MIME types are inferred by the serving platform from the retained path.
+                // eslint-disable-next-line no-await-in-loop
+                const bytes = await fs.readFile(path.join(directory, name));
+                files.push(packageFile('asset', name, 'application/octet-stream', bytes));
+            }
+            else {
+                throw new Error(`Unsupported frontend asset (symlink or special file): ${name}`);
+            }
+        }
+    }
+    await walk();
+    return files;
+}
+async function readServingControl(directory, name) {
+    const filename = path.join(directory, name);
+    const stat = await fs.lstat(filename).catch((error) => {
+        if (error.code !== 'ENOENT')
+            throw error;
+    });
+    if (!stat)
+        return undefined;
+    if (!stat.isFile())
+        throw new Error(`Frontend serving control must be a regular file: ${name}`);
+    return fs.readFile(filename, 'utf8');
+}
+// Link in memory only: no module is executed and no rebuilt bytes enter the package.
+export async function checkModuleGraph(pkg) {
+    const modules = new Map(pkg.files
+        .filter((file) => file.kind === 'module')
+        .map((file) => [file.path, file]));
+    await build({
+        entryPoints: [pkg.entrypoint],
+        bundle: true,
+        write: false,
+        platform: 'neutral',
+        format: 'esm',
+        logLevel: 'silent',
+        plugins: [
+            {
+                name: 'retained-frontend-modules',
+                setup(builder) {
+                    builder.onResolve({ filter: /.*/ }, (args) => {
+                        if (/^(?:node|cloudflare):/.test(args.path))
+                            return { path: args.path, external: true };
+                        const name = args.kind === 'entry-point'
+                            ? args.path
+                            : path.posix.join(path.posix.dirname(args.importer), args.path);
+                        if (!modules.has(name))
+                            throw new Error(`Missing frontend Worker module: ${name}`);
+                        return { path: name, namespace: 'frontend' };
+                    });
+                    builder.onLoad({ filter: /.*/, namespace: 'frontend' }, (args) => {
+                        const file = modules.get(args.path);
+                        const loaders = {
+                            'application/javascript+module': 'js',
+                            'text/plain': 'text',
+                            'application/wasm': 'binary',
+                            'application/octet-stream': 'binary',
+                        };
+                        const loader = loaders[file.content_type];
+                        if (!loader)
+                            throw new Error(`Unsupported frontend Worker module type: ${file.content_type}`);
+                        return { contents: Buffer.from(file.data, 'base64'), loader };
+                    });
+                },
+            },
+        ],
+    });
+}
+async function localBin(frontend, name) {
+    const require = createRequire(path.join(frontend, 'package.json'));
+    for (const directory of require.resolve.paths(name) ?? []) {
+        const manifest = path.join(directory, name, 'package.json');
+        // Packages may intentionally omit package.json from their exports.
+        // eslint-disable-next-line no-await-in-loop
+        const text = await fs.readFile(manifest, 'utf8').catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return null;
+        });
+        if (!text)
+            continue;
+        const pkg = JSON.parse(text);
+        const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin[name];
+        return path.resolve(path.dirname(manifest), bin);
+    }
+    throw new Error(`Install ${name} in the frontend workspace before building a managed package`);
+}
+async function runLocal(frontend, name, args, temp) {
+    await execa(process.execPath, [await localBin(frontend, name), ...args], {
+        cwd: frontend,
+        env: {
+            CI: '1',
+            WRANGLER_SEND_METRICS: 'false',
+            WRANGLER_LOG_PATH: path.join(temp, 'wrangler.log'),
+        },
+    });
+}
+// Capture actual Wrangler modules plus the separate complete public asset inventory.
+export async function captureFrontendPackage(frontend, framework) {
+    frontend = path.resolve(frontend);
+    const temp = await fs.mkdtemp(path.join(os.tmpdir(), 'swell-frontend-package-'));
+    try {
+        let configPath = path.join(frontend, 'dist/server/wrangler.json');
+        if (framework === 'react') {
+            const manifest = JSON.parse(await fs.readFile(path.join(frontend, 'package.json'), 'utf8'));
+            const usesCloudflarePlugin = manifest.dependencies?.['@cloudflare/vite-plugin'] ||
+                manifest.devDependencies?.['@cloudflare/vite-plugin'];
+            if (usesCloudflarePlugin) {
+                const redirectPath = path.join(frontend, '.wrangler/deploy/config.json');
+                const redirect = JSON.parse(await fs.readFile(redirectPath, 'utf8').catch((error) => {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                    throw new Error('Cloudflare Vite build is missing its deployment config. Build the frontend before packaging.');
+                }));
+                if (typeof redirect.configPath !== 'string' || !redirect.configPath)
+                    throw new Error('Cloudflare Vite build is missing configPath');
+                configPath = path.resolve(path.dirname(redirectPath), redirect.configPath);
+            }
+            else {
+                configPath = path.join(temp, 'wrangler.json');
+                await fs.writeFile(path.join(temp, 'worker.js'), 'export default { fetch(request, env) { return env.ASSETS.fetch(request); } };\n');
+                await fs.writeFile(configPath, JSON.stringify({
+                    name: 'swell-managed-react',
+                    main: './worker.js',
+                    compatibility_date: '2026-09-08',
+                    assets: {
+                        directory: path.join(frontend, 'dist'),
+                        binding: 'ASSETS',
+                        not_found_handling: 'single-page-application',
+                        html_handling: 'none',
+                    },
+                }));
+            }
+        }
+        const config = JSON.parse(await fs.readFile(configPath, 'utf8'));
+        if (!config.assets?.directory)
+            throw new Error('Managed frontend build must declare an assets directory');
+        const assetDirectory = path.resolve(path.dirname(configPath), config.assets.directory);
+        await runLocal(frontend, 'wrangler', [
+            'deploy',
+            '--dry-run',
+            '--config',
+            configPath,
+            '--outdir',
+            path.join(temp, 'worker'),
+            '--outfile',
+            path.join(temp, 'upload.multipart'),
+            '--upload-source-maps=false',
+        ], temp);
+        const raw = await fs.readFile(path.join(temp, 'upload.multipart'));
+        const boundary = raw.subarray(2, raw.indexOf('\r\n')).toString();
+        const form = await new Response(raw, {
+            headers: {
+                'content-type': `multipart/form-data; boundary=${boundary}`,
+            },
+        }).formData();
+        const metadataPart = form.get('metadata');
+        if (!metadataPart)
+            throw new Error('Wrangler output is missing metadata');
+        const metadata = JSON.parse(typeof metadataPart === 'string'
+            ? metadataPart
+            : await metadataPart.text());
+        const files = await collectAssets(assetDirectory);
+        for (const [name, part] of form) {
+            if (name === 'metadata')
+                continue;
+            if (typeof part === 'string')
+                throw new Error(`Invalid Worker module: ${name}`);
+            if (name.endsWith('.map'))
+                continue;
+            files.push(packageFile('module', name, part.type, 
+            // eslint-disable-next-line no-await-in-loop
+            Buffer.from(await part.arrayBuffer())));
+        }
+        const bindings = (metadata.bindings ?? []).map((binding) => {
+            if ((binding.type === 'assets' && binding.name === 'ASSETS') ||
+                (framework === 'vinext' &&
+                    binding.type === 'version_metadata' &&
+                    binding.name === 'CF_VERSION_METADATA')) {
+                return binding.name;
+            }
+            throw new Error(`Unsupported managed frontend binding: ${binding.name}`);
+        });
+        const { assets, cache } = config;
+        const [_headers, _redirects] = await Promise.all([
+            readServingControl(assetDirectory, '_headers'),
+            readServingControl(assetDirectory, '_redirects'),
+        ]);
+        if (assets.run_worker_first !== undefined &&
+            typeof assets.run_worker_first !== 'boolean') {
+            throw new Error('Managed frontend assets.run_worker_first must be boolean');
+        }
+        const pkg = {
+            format: 1,
+            framework,
+            entrypoint: metadata.main_module,
+            runtime: {
+                compatibility_date: metadata.compatibility_date,
+                compatibility_flags: metadata.compatibility_flags ?? [],
+                bindings: bindings.sort(),
+                cache: cache?.enabled === true,
+            },
+            assets: {
+                ...(_headers === undefined ? {} : { _headers }),
+                ...(_redirects === undefined ? {} : { _redirects }),
+                html_handling: assets.html_handling ?? 'auto-trailing-slash',
+                not_found_handling: assets.not_found_handling ?? 'none',
+                run_worker_first: assets.run_worker_first ?? false,
+            },
+            files: files.sort(compareFiles),
+            digest: '',
+        };
+        pkg.digest = frontendPackageDigest(pkg);
+        verifyFrontendPackage(pkg);
+        await checkModuleGraph(pkg);
+        return pkg;
+    }
+    finally {
+        await fs.rm(temp, { recursive: true, force: true });
+    }
+}
+// Always rebuild: source-only hashes miss imported workspace files and dependencies.
+export async function buildFrontendPackage(frontend, framework) {
+    frontend = path.resolve(frontend);
+    const temp = await fs.mkdtemp(path.join(os.tmpdir(), 'swell-frontend-build-'));
+    try {
+        await runLocal(frontend, framework === 'vinext' ? 'vinext' : 'vite', ['build'], temp);
+        return await captureFrontendPackage(frontend, framework);
+    }
+    finally {
+        await fs.rm(temp, { recursive: true, force: true });
+    }
+}
+// Hosting is explicit; an unsupported managed project never falls back to Wrangler deploy.
+export async function getManagedFrontendFramework(frontend) {
+    let manifestText;
+    try {
+        manifestText = await fs.readFile(path.join(frontend, 'package.json'), 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        throw new Error('Managed hosting requires a frontend/ directory with a package.json. Run swell create frontend, or set frontend.hosting to self-hosted.');
+    }
+    const manifest = JSON.parse(manifestText);
+    const dependencies = {
+        ...manifest.dependencies,
+        ...manifest.devDependencies,
+    };
+    if (dependencies['@opennextjs/cloudflare'] ||
+        (dependencies.next && !dependencies.vinext)) {
+        throw new Error('OpenNext and Next.js require frontend.hosting: self-hosted. Managed hosting supports Vinext or client-side React+Vite.');
+    }
+    if (dependencies.vinext)
+        return 'vinext';
+    if (dependencies.react && dependencies.vite)
+        return 'react';
+    throw new Error('Managed hosting requires Vinext or client-side React+Vite in frontend/package.json.');
+}

package/dist/lib/apps/frontend-routes.d.ts

@@ -0,0 +1 @@
+export declare function warnFrontendRouteCollisions(appPath: string, framework: string, warn: (message: string) => void): Promise<void>;

package/dist/lib/apps/frontend-routes.js

@@ -0,0 +1,40 @@
+import { globby } from 'globby';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+// Inspect conventional filesystem handlers only. Browser calls to /api are valid
+// Swell requests, and arbitrary Worker routing cannot be inferred from filenames.
+export async function warnFrontendRouteCollisions(appPath, framework, warn) {
+    if (!['nextjs', 'vinext'].includes(framework))
+        return;
+    const frontend = path.join(appPath, 'frontend');
+    const root = (name) => existsSync(path.join(frontend, name)) ? name : `src/${name}`;
+    const appRoot = root('app');
+    const pagesRoot = root('pages');
+    const files = await globby([
+        `${appRoot}/**/route.{js,jsx,ts,tsx}`,
+        `${pagesRoot}/api/**/*.{js,jsx,ts,tsx}`,
+        '!**/*.d.ts',
+    ], { cwd: frontend, onlyFiles: true });
+    for (const file of files.sort()) {
+        const segments = file.startsWith(`${appRoot}/`)
+            ? appRouteSegments(file.slice(appRoot.length + 1))
+            : pagesRouteSegments(file.slice(pagesRoot.length + 1));
+        if (segments?.[0] === 'api') {
+            warn(`frontend/${file} declares /${segments.join('/')}, which Swell owns on Swell-routed domains. Use an unreserved frontend path such as /app-api, or explicitly configure the selected app's compatibility prefix for existing /api handlers.`);
+        }
+    }
+}
+// App Router: (group)/api/quote/route.ts declares /api/quote; _private is skipped.
+function appRouteSegments(file) {
+    const segments = file.split('/').slice(0, -1);
+    if (segments.some((segment) => segment.startsWith('_')))
+        return undefined;
+    return segments.filter((segment) => !/^\([^)]*\)$/.test(segment));
+}
+// Pages Router: api/quote/index.ts and api/quote.ts both declare /api/quote.
+function pagesRouteSegments(file) {
+    const segments = file.replace(/\.[^.]+$/, '').split('/');
+    if (segments.at(-1) === 'index')
+        segments.pop();
+    return segments;
+}

package/dist/lib/apps/frontend-scaffold.d.ts

@@ -0,0 +1,35 @@
+import type { FrontendTemplate } from './frontend-templates.js';
+import { PackageManager } from '../package-manager.js';
+/** Allowed hosts for tunnel providers used in local development */
+export declare const TUNNEL_ALLOWED_HOSTS: string[];
+/**
+ * Configure allowedHosts for frameworks using Vite dev server.
+ * This allows tunneling services (localtunnel) to proxy requests to the
+ * local dev environment.
+ */
+export declare function addFrontendAllowedHosts(framework: string, configPath: string): Promise<void>;
+/** Write the root workspace files and install root dependencies. */
+export declare function setupPackage(name: string, config: any, pkg: PackageManager): Promise<void>;
+/**
+ * Remove the empty workspace placeholder created by setupPackage; refuse to
+ * scaffold over any other content in frontend/.
+ */
+export declare function prepareFrontendDirectory(configPath: string): Promise<void>;
+/** Create the root workspace, or add frontend to an existing one. */
+export declare function ensureRootWorkspace(swellConfig: any, pkg: PackageManager): Promise<void>;
+/**
+ * pnpm's native build policy must include the two toolchain binaries.
+ * Use pnpm to merge its YAML settings without replacing other entries.
+ */
+export declare function ensurePnpmBuildApprovals(configPath: string): Promise<void>;
+/** Run the template's scaffold command into frontend/. */
+export declare function scaffoldFrontendTemplate(configPath: string, template: FrontendTemplate, pkg: PackageManager): Promise<void>;
+/**
+ * The template finalizer restores the pinned declarations and managed
+ * settings that C3 rewrites while scaffolding.
+ */
+export declare function finalizeManagedFrontend(frontendPath: string): Promise<void>;
+/** Ensure frontend package.json has the correct name for the workspace. */
+export declare function normalizeFrontendManifest(frontendPath: string, template: FrontendTemplate): Promise<void>;
+/** Run install at root to hoist dependencies to the workspace. */
+export declare function installFrontendWorkspace(configPath: string, template: FrontendTemplate, pkg: PackageManager): Promise<void>;