extension-create 4.0.25 → 4.0.27

package/dist/lib/messages.d.ts

@@ -13,6 +13,7 @@ export declare function installingFromTemplateError(template: string, error: unk
 export declare function templateFetchTimedOut(templateName: string, ms: number): string;
 export declare function templateNotFoundInCatalog(templateName: string, error?: unknown): string;
 export declare function templateDownloadFailed(templateName: string, error: unknown): string;
+export declare function removedStaleTemplateLockfiles(fileNames: string[]): string;
 export declare function initializingGitForRepository(projectName: string): string;
 export declare function initializingGitSkipped(projectName: string, reason: string): string;
 export declare function firstCommitSkipped(projectName: string, reason: string): string;
@@ -22,6 +23,7 @@ export declare function installingProjectIntegrations(integrations: string[]): s
 export declare function installingDependenciesFailed(pmCommand: string, pmArgs: string[], code: number | null): string;
 export declare function installingDependenciesProcessError(projectName: string, error: unknown): string;
 export declare function cantInstallDependencies(projectName: string, error: unknown): string;
+export declare function malformedPackageJson(packageJsonPath: string, error: unknown): string;
 export declare function writingPackageJsonMetadata(): string;
 export declare function writingPackageJsonMetadataError(error: unknown): string;
 export declare function writingDenoJsonc(): string;

package/dist/module.cjs

@@ -195,7 +195,7 @@ function writingTypeDefinitionsError(error) {
     return `${prefix('error')} Couldn't write the extension type definitions.\n${fmt.label('REASON')} ${fmt.val(fmt.truncate(String(error)))}\n${external_pintor_default().red('Check the file permissions, then try again.')}`;
 }
 function installingFromTemplate(projectName, templateName) {
-    if ('init' === templateName || "javascript" === templateName) return `${prefix('info')} Copying the template files…`;
+    if ("javascript" === templateName) return `${prefix('info')} Copying the template files…`;
     return `${prefix('info')} Copying the template ${external_pintor_default().blue(templateName)}…`;
 }
 function usingTemplate(templateName, source) {
@@ -214,6 +214,9 @@ function templateNotFoundInCatalog(templateName, error) {
 function templateDownloadFailed(templateName, error) {
     return `${prefix('error')} Couldn't download the template ${external_pintor_default().blue(templateName)} from ${fmt.val('github.com/extension-js/examples')}.\n${fmt.label('REASON')} ${fmt.val(fmt.truncate(String(error?.message || error)))}\n${external_pintor_default().red('- Check your network connection and any GitHub rate limit, then try again.')}\n${external_pintor_default().red('- Set')} ${external_pintor_default().blue('EXTENSION_CREATE_TIMEOUT_MS')} ${external_pintor_default().red('to allow more time.')}`;
 }
+function removedStaleTemplateLockfiles(fileNames) {
+    return `${prefix('info')} Removed the template ${fileNames.map((name)=>fmt.val(name)).join(', ')}. The first install writes a fresh one.`;
+}
 function initializingGitForRepository(projectName) {
     return `${prefix('debug')} create git init name=${projectName}`;
 }
@@ -248,6 +251,9 @@ function installingDependenciesProcessError(projectName, error) {
 function cantInstallDependencies(projectName, error) {
     return `${prefix('error')} Couldn't install the dependencies for ${external_pintor_default().blue(projectName)}.\n${fmt.label('REASON')} ${fmt.val(fmt.truncate(String(error?.message || error)))}\n${external_pintor_default().red('Check your package manager settings, then try again.')}`;
 }
+function malformedPackageJson(packageJsonPath, error) {
+    return `${prefix('warn')} Couldn't parse ${external_pintor_default().blue('package.json')}, so no integrations were detected.\n${fmt.label('PATH')} ${fmt.val(packageJsonPath)}\n${fmt.label('REASON')} ${fmt.val(fmt.truncate(String(error?.message || error)))}`;
+}
 function writingPackageJsonMetadata() {
     return `${prefix('debug')} create write file=package.json`;
 }
@@ -377,12 +383,14 @@ async function isDirectoryWriteable(directory, logger) {
 function isTypeScriptTemplate(templateName) {
     return templateName.includes("typescript") || templateName.includes('react') || templateName.includes('preact') || templateName.includes('svelte') || templateName.includes('solid');
 }
+const external_node_fs_namespaceObject = require("node:fs");
 const allowlist = [
     'LICENSE',
     'node_modules'
 ];
 async function createDirectory(projectPath, projectName, logger) {
     logger.log(startingNewExtension(projectName));
+    const directoryPreExisted = (0, external_node_fs_namespaceObject.existsSync)(projectPath);
     try {
         const isCurrentDirWriteable = await isDirectoryWriteable(projectPath, logger);
         if (!isCurrentDirWriteable) {
@@ -401,6 +409,9 @@ async function createDirectory(projectPath, projectName, logger) {
     } catch (error) {
         throw new Error(createDirectoryError(projectName, error));
     }
+    return {
+        directoryCreated: !directoryPreExisted
+    };
 }
 async function generateExtensionTypes(projectPath, projectName, logger) {
     const extensionEnvFile = external_node_path_namespaceObject.join(projectPath, 'extension-env.d.ts');
@@ -427,7 +438,6 @@ async function generateExtensionTypes(projectPath, projectName, logger) {
         throw error;
     }
 }
-const external_node_fs_namespaceObject = require("node:fs");
 const external_node_os_namespaceObject = require("node:os");
 const external_adm_zip_namespaceObject = require("adm-zip");
 var external_adm_zip_default = /*#__PURE__*/ __webpack_require__.n(external_adm_zip_namespaceObject);
@@ -589,6 +599,28 @@ async function removeTemplateScaffoldingFiles(projectPath) {
             force: true
         })));
 }
+const TEMPLATE_LOCKFILE_NAMES = [
+    'package-lock.json',
+    'npm-shrinkwrap.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'bun.lockb',
+    'bun.lock',
+    'deno.lock'
+];
+async function removeStaleTemplateLockfiles(projectPath) {
+    const removed = [];
+    for (const name of TEMPLATE_LOCKFILE_NAMES){
+        const target = external_node_path_namespaceObject.join(projectPath, name);
+        if ((0, external_node_fs_namespaceObject.existsSync)(target)) {
+            await promises_namespaceObject.rm(target, {
+                force: true
+            });
+            removed.push(name);
+        }
+    }
+    return removed;
+}
 function getArchiveBaseName(url) {
     const withoutQuery = url.split('?')[0];
     const fileName = external_node_path_namespaceObject.basename(withoutQuery);
@@ -611,12 +643,35 @@ async function getZipSourcePath(tempPath, templateUrl) {
     if (onlyDir.name === archiveBase) return external_node_path_namespaceObject.join(tempPath, onlyDir.name);
     return tempPath;
 }
-async function importExternalTemplate(projectPath, projectName, template, logger) {
+async function cleanupFailedImport(projectPath, ownsProjectDir, preExistingEntries) {
+    if (ownsProjectDir) return void await promises_namespaceObject.rm(projectPath, {
+        recursive: true,
+        force: true
+    }).catch(()=>{});
+    const keep = new Set(preExistingEntries);
+    let entries = [];
+    try {
+        entries = await promises_namespaceObject.readdir(projectPath);
+    } catch  {
+        return;
+    }
+    await Promise.all(entries.filter((entry)=>!keep.has(entry)).map((entry)=>promises_namespaceObject.rm(external_node_path_namespaceObject.join(projectPath, entry), {
+            recursive: true,
+            force: true
+        }).catch(()=>{})));
+}
+async function importExternalTemplate(projectPath, projectName, template, logger, options) {
     const templateName = external_node_path_namespaceObject.basename(template);
-    const resolvedTemplate = 'init' === templateName ? "javascript" : template;
-    const resolvedTemplateName = 'init' === templateName ? "javascript" : templateName;
+    const resolvedTemplate = template;
+    const resolvedTemplateName = templateName;
     const isHttp = /^https?:\/\//i.test(template);
     const isGithub = /^https?:\/\/github\.com\//i.test(template);
+    const dirExistedBeforeImport = (0, external_node_fs_namespaceObject.existsSync)(projectPath);
+    const ownsProjectDir = options?.ownsProjectDir ?? !dirExistedBeforeImport;
+    let preExistingEntries = [];
+    if (dirExistedBeforeImport) try {
+        preExistingEntries = await promises_namespaceObject.readdir(projectPath);
+    } catch  {}
     try {
         await promises_namespaceObject.mkdir(projectPath, {
             recursive: true
@@ -626,6 +681,8 @@ async function importExternalTemplate(projectPath, projectName, template, logger
             if ((0, external_node_fs_namespaceObject.existsSync)(localTemplate)) {
                 await copyDirectoryWithSymlinks(localTemplate, projectPath);
                 await removeTemplateScaffoldingFiles(projectPath);
+                const dropped = await removeStaleTemplateLockfiles(projectPath);
+                if (dropped.length) logger.log(removedStaleTemplateLockfiles(dropped));
                 return {
                     template: resolvedTemplateName,
                     source: 'bundled'
@@ -696,6 +753,8 @@ async function importExternalTemplate(projectPath, projectName, template, logger
             };
         }
         await removeTemplateScaffoldingFiles(projectPath);
+        const droppedLockfiles = await removeStaleTemplateLockfiles(projectPath);
+        if (droppedLockfiles.length) logger.log(removedStaleTemplateLockfiles(droppedLockfiles));
         await promises_namespaceObject.rm(tempRoot, {
             recursive: true,
             force: true
@@ -705,10 +764,7 @@ async function importExternalTemplate(projectPath, projectName, template, logger
         if (error instanceof TemplateNotFoundError) logger.error(templateNotFoundInCatalog(templateName, error.cause));
         else if (error instanceof TemplateDownloadError) logger.error(templateDownloadFailed(templateName, error));
         else logger.error(installingFromTemplateError(templateName, error));
-        await promises_namespaceObject.rm(projectPath, {
-            recursive: true,
-            force: true
-        }).catch(()=>{});
+        await cleanupFailedImport(projectPath, ownsProjectDir, preExistingEntries);
         throw error;
     }
 }
@@ -1025,25 +1081,25 @@ function parseNpmSpecifier(specifier) {
 }
 function readDenoConfigDependencies(projectPath) {
     const dependencies = {};
-    for (const filename of [
-        'deno.jsonc',
-        'deno.json'
-    ]){
-        const configPath = external_node_path_namespaceObject.join(projectPath, filename);
-        let config;
-        try {
-            config = parseJsoncSafe(external_node_fs_namespaceObject.readFileSync(configPath, 'utf8'));
-        } catch  {
-            continue;
-        }
-        const imports = config?.imports;
-        if (imports && 'object' == typeof imports) for (const [rawAlias, specifier] of Object.entries(imports)){
-            const parsed = parseNpmSpecifier(specifier);
-            if (!parsed) continue;
-            dependencies[parsed.name] = dependencies[parsed.name] || parsed.version;
-            const alias = rawAlias.endsWith('/') ? rawAlias.slice(0, -1) : rawAlias;
-            if (alias && alias !== parsed.name) dependencies[alias] = dependencies[alias] || parsed.version;
-        }
+    const filename = [
+        'deno.json',
+        'deno.jsonc'
+    ].find((candidate)=>external_node_fs_namespaceObject.existsSync(external_node_path_namespaceObject.join(projectPath, candidate)));
+    if (!filename) return dependencies;
+    let config;
+    try {
+        config = parseJsoncSafe(external_node_fs_namespaceObject.readFileSync(external_node_path_namespaceObject.join(projectPath, filename), 'utf8'));
+    } catch  {
+        return dependencies;
+    }
+    const imports = config?.imports;
+    if (!imports || 'object' != typeof imports) return dependencies;
+    for (const [rawAlias, specifier] of Object.entries(imports)){
+        const parsed = parseNpmSpecifier(specifier);
+        if (!parsed) continue;
+        dependencies[parsed.name] = dependencies[parsed.name] || parsed.version;
+        const alias = rawAlias.endsWith('/') ? rawAlias.slice(0, -1) : rawAlias;
+        if (alias && alias !== parsed.name) dependencies[alias] = dependencies[alias] || parsed.version;
     }
     return dependencies;
 }
@@ -1068,12 +1124,15 @@ function resolveDevelopRoot(projectPath) {
         return null;
     }
 }
-function readPackageJson(projectPath) {
+function readPackageJson(projectPath, logger) {
     let pkg = {};
+    const packageJsonPath = external_node_path_namespaceObject.join(projectPath, 'package.json');
     try {
-        const raw = external_node_fs_namespaceObject.readFileSync(external_node_path_namespaceObject.join(projectPath, 'package.json'), 'utf8');
+        const raw = external_node_fs_namespaceObject.readFileSync(packageJsonPath, 'utf8');
         pkg = JSON.parse(raw);
-    } catch  {}
+    } catch (error) {
+        if (error?.code !== 'ENOENT') logger.log(malformedPackageJson(packageJsonPath, error));
+    }
     const denoDependencies = readDenoConfigDependencies(projectPath);
     if (Object.keys(denoDependencies).length > 0) pkg = {
         ...pkg,
@@ -1100,8 +1159,8 @@ function canResolve(dependency, paths) {
 function findConfigFile(projectPath, candidates) {
     return candidates.some((file)=>external_node_fs_namespaceObject.existsSync(external_node_path_namespaceObject.join(projectPath, file)));
 }
-function detectOptionalDependencies(projectPath) {
-    const pkg = readPackageJson(projectPath);
+function detectOptionalDependencies(projectPath, logger) {
+    const pkg = readPackageJson(projectPath, logger);
     const usesReact = hasDependency(pkg, 'react') || hasDependency(pkg, 'react-dom');
     const usesPreact = hasDependency(pkg, 'preact');
     const usesVue = hasDependency(pkg, 'vue');
@@ -1194,7 +1253,8 @@ function buildOptionalInstallArgs(pm, dependencies, installDir) {
         ...dependencies,
         '--dir',
         installDir,
-        '--save-optional'
+        '--save-optional',
+        '--silent'
     ];
     if ('bun' === pm) return [
         'add',
@@ -1210,8 +1270,8 @@ function buildOptionalInstallArgs(pm, dependencies, installDir) {
         '--legacy-peer-deps'
     ];
 }
-function resolveMissingOptionalDeps(developRoot, projectPath) {
-    const plan = detectOptionalDependencies(projectPath);
+function resolveMissingOptionalDeps(developRoot, projectPath, logger) {
+    const plan = detectOptionalDependencies(projectPath, logger);
     const dependenciesByIntegration = {};
     const integrations = [];
     const missing = new Set();
@@ -1260,7 +1320,7 @@ async function installInternalDependencies(projectPath, logger) {
     if ('test' === process.env.EXTENSION_ENV || 'true' === process.env.EXTENSION_SKIP_INTERNAL_INSTALL) return;
     const developRoot = resolveDevelopRoot(projectPath);
     if (!developRoot) return;
-    const optionalPlan = resolveMissingOptionalDeps(developRoot, projectPath);
+    const optionalPlan = resolveMissingOptionalDeps(developRoot, projectPath, logger);
     if (optionalPlan.dependencies.length > 0) await installOptionalDependencies(developRoot, projectPath, optionalPlan, logger);
 }
 async function setupBuiltInTests(projectPath, logger) {
@@ -1476,16 +1536,31 @@ async function collectTemplateImports(projectPath, cliVersion) {
 }
 async function writeDenoJsonc(projectPath, { template = "javascript", cliVersion, primary = false }, logger) {
     if (!isDenoRuntime()) return;
-    for (const existing of [
-        'deno.jsonc',
-        'deno.json'
-    ])if (await pathExists(external_node_path_namespaceObject.join(projectPath, existing))) return;
+    let existingConfig;
+    for (const candidate of [
+        'deno.json',
+        'deno.jsonc'
+    ])if (await pathExists(external_node_path_namespaceObject.join(projectPath, candidate))) {
+        existingConfig = candidate;
+        break;
+    }
+    if (existingConfig && !primary) return;
     const extensionBinary = await resolveExtensionBinary();
     const tasks = getTemplateAwareScripts(template, extensionBinary);
     const imports = primary ? await collectTemplateImports(projectPath, cliVersion) : void 0;
     try {
         if (isDebug()) logger.log(writingDenoJsonc());
-        await promises_namespaceObject.writeFile(external_node_path_namespaceObject.join(projectPath, 'deno.jsonc'), renderDenoJsonc(tasks, imports));
+        if (existingConfig) {
+            const configPath = external_node_path_namespaceObject.join(projectPath, existingConfig);
+            const config = parseJsoncSafe(await promises_namespaceObject.readFile(configPath, 'utf8'));
+            config.imports = {
+                ...imports || {},
+                ...config.imports || {}
+            };
+            if (void 0 === config.nodeModulesDir) config.nodeModulesDir = 'auto';
+            if (!config.tasks) config.tasks = tasks;
+            await promises_namespaceObject.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+        } else await promises_namespaceObject.writeFile(external_node_path_namespaceObject.join(projectPath, 'deno.jsonc'), renderDenoJsonc(tasks, imports));
         if (primary) await promises_namespaceObject.rm(external_node_path_namespaceObject.join(projectPath, 'package.json'), {
             force: true
         });
@@ -1522,6 +1597,9 @@ const localSessionState = [
 const envFiles = [
     '',
     '# local env files',
+    '.env',
+    '.env*',
+    '!.env.example',
     '.env.local',
     '.env.development.local',
     '.env.test.local',
@@ -1646,11 +1724,12 @@ async function writeReadmeFile(projectPath, projectName, logger) {
     const manifestJsonPath = await findManifestJsonPath(projectPath);
     const manifestJson = JSON.parse(await promises_namespaceObject.readFile(manifestJsonPath, 'utf-8'));
     const description = String(manifestJson.description || '').trim();
-    const screenshotPath = external_node_path_namespaceObject.join(projectPath, 'public', 'screenshot.png');
-    const hasScreenshot = await write_readme_file_pathExists(screenshotPath);
-    const screenshotEmbed = hasScreenshot ? `\n![screenshot](./public/screenshot.png)\n` : '';
+    const hasPublicScreenshot = await write_readme_file_pathExists(external_node_path_namespaceObject.join(projectPath, 'public', 'screenshot.png'));
+    const hasRootScreenshot = await write_readme_file_pathExists(external_node_path_namespaceObject.join(projectPath, 'screenshot.png'));
+    const screenshotHref = hasPublicScreenshot ? './public/screenshot.png' : hasRootScreenshot ? './screenshot.png' : null;
+    const screenshotEmbed = screenshotHref ? `\n![screenshot](${screenshotHref})\n` : '';
     const blockquote = description ? `> ${description}\n\n` : '';
-    const readme = `<a href="https://extension.js.org" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Powered%20by%20%7C%20Extension.js-0971fe" alt="Powered by Extension.js" align="right" /></a>\n\n# ${projectName}\n\n` + blockquote + `${screenshotEmbed}` + `## Commands\n` + `\n` + `### dev\n` + `\n` + "Run the extension in development mode. Target a browser with `--browser`:\n" + `\n` + "```bash\n" + `${runPrefix} dev\n` + `${runPrefix} dev${argSeparator} --browser=firefox\n` + `${runPrefix} dev${argSeparator} --browser=edge\n` + "```\n" + `\n` + `### build\n` + `\n` + `Build for production. Convenience scripts target each browser:\n` + `\n` + "```bash\n" + `${runPrefix} build           # Chrome (default)\n` + `${runPrefix} build:firefox\n` + `${runPrefix} build:edge\n` + "```\n" + `\n` + `### preview\n` + `\n` + `Preview the production build in the browser:\n` + `\n` + "```bash\n" + `${runPrefix} preview\n` + "```\n" + `\n` + `## Learn more\n` + `\n` + `[Extension.js docs](https://extension.js.org).\n` + `\n` + `## Ship it\n` + `\n` + "Building and running your extension is local and free. When you are ready to share a build or submit it to the stores, [extension.dev](https://docs.extension.dev/publish/overview?utm_source=create-readme) " + `does that side and sponsors Extension.js.\n`;
+    const readme = `<a href="https://extension.js.org" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Powered%20by%20%7C%20Extension.js-0971fe" alt="Powered by Extension.js" align="right" /></a>\n\n# ${projectName}\n\n` + blockquote + `${screenshotEmbed}` + `## Commands\n` + `\n` + `### dev\n` + `\n` + "Run the extension in development mode. Target a browser with `--browser`:\n" + `\n` + "```bash\n" + `${runPrefix} dev\n` + `${runPrefix} dev${argSeparator} --browser=firefox\n` + `${runPrefix} dev${argSeparator} --browser=edge\n` + "```\n" + `\n` + `### build\n` + `\n` + `Build for production. Convenience scripts target each browser:\n` + `\n` + "```bash\n" + `${runPrefix} build           # Chromium (default)\n` + `${runPrefix} build:firefox\n` + `${runPrefix} build:edge\n` + "```\n" + `\n` + `### preview\n` + `\n` + `Preview the production build in the browser:\n` + `\n` + "```bash\n" + `${runPrefix} preview\n` + "```\n" + `\n` + `## Learn more\n` + `\n` + `[Extension.js docs](https://extension.js.org).\n` + `\n` + `## Ship it\n` + `\n` + "Building and running your extension is local and free. When you are ready to share a build or submit it to the stores, [extension.dev](https://docs.extension.dev/publish/overview?utm_source=create-readme) " + `does that side and sponsors Extension.js.\n`;
     try {
         if (isDebug()) logger.log(writingReadmeMetaData());
         await promises_namespaceObject.mkdir(projectPath, {
@@ -1666,11 +1745,13 @@ const STORE_METADATA_FILE = 'STORE.md';
 function escapeForRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+const NAME_PLACEHOLDER = '\u0000extension-create-name\u0000';
 function rewriteStoreMetadata(content, projectName, templateName, today) {
-    let next = content.replace(/^(\s*-\s*Name:).*$/m, (_match, label)=>`${label} ${projectName}`);
-    if (templateName && templateName !== projectName) next = next.replace(new RegExp(escapeForRegExp(templateName), 'g'), projectName);
+    let next = content;
+    if (templateName && templateName !== projectName) next = next.replace(new RegExp(escapeForRegExp(templateName), 'g'), NAME_PLACEHOLDER);
+    next = next.replace(/^(\s*-\s*Name:).*$/m, (_match, label)=>`${label} ${NAME_PLACEHOLDER}`);
     next = next.replace(/^(Last updated:).*$/m, (_match, label)=>`${label} ${today}`);
-    return next;
+    return next.split(NAME_PLACEHOLDER).join(projectName);
 }
 async function writeStoreMetadata(projectPath, projectName, templateName, logger) {
     const storePath = external_node_path_namespaceObject.join(projectPath, STORE_METADATA_FILE);
@@ -1728,7 +1809,7 @@ async function extensionCreate(projectNameInput, { cliVersion, template = "javas
     const projectName = external_node_path_namespaceObject.basename(projectPath);
     const updateSuffix = process.env.EXTENSION_CLI_UPDATE_SUFFIX || '';
     if (updateSuffix) delete process.env.EXTENSION_CLI_UPDATE_SUFFIX;
-    const requestedTemplate = 'init' === external_node_path_namespaceObject.basename(String(template)) ? "javascript" : String(template);
+    const requestedTemplate = String(template);
     logger.log(' ');
     logger.log(card({
         version: cliVersion || process.env.EXTENSION_CLI_VERSION,
@@ -1750,8 +1831,10 @@ async function extensionCreate(projectNameInput, { cliVersion, template = "javas
     }));
     logger.log(' ');
     process.env.EXTENSION_CLI_BANNER_PRINTED = 'true';
-    await createDirectory(projectPath, projectName, logger);
-    const templateProvenance = await importExternalTemplate(projectPath, projectName, template, logger);
+    const createResult = await createDirectory(projectPath, projectName, logger);
+    const templateProvenance = await importExternalTemplate(projectPath, projectName, template, logger, {
+        ownsProjectDir: createResult?.directoryCreated ?? false
+    });
     if (templateProvenance?.template) logger.log(usingTemplate(templateProvenance.template, templateProvenance.source));
     const isMonorepoTemplate = String(template).toLowerCase().includes('monorepo');
     if (isDenoRuntime() && !isMonorepoTemplate) await writeDenoJsonc(projectPath, {

package/dist/steps/create-directory.d.ts

@@ -1,4 +1,7 @@
+export interface CreateDirectoryResult {
+    directoryCreated: boolean;
+}
 export declare function createDirectory(projectPath: string, projectName: string, logger: {
     log(...args: unknown[]): void;
     error(...args: unknown[]): void;
-}): Promise<void>;
+}): Promise<CreateDirectoryResult>;

package/dist/steps/import-external-template.d.ts

@@ -15,7 +15,13 @@ export declare class TemplateDownloadError extends Error {
 export declare function extractExamplesTemplateFromZip(zipBuffer: Buffer, templateName: string, projectPath: string): Promise<number>;
 export declare const TEMPLATE_SCAFFOLDING_FILES: string[];
 export declare function removeTemplateScaffoldingFiles(projectPath: string): Promise<void>;
+export declare const TEMPLATE_LOCKFILE_NAMES: string[];
+export declare function removeStaleTemplateLockfiles(projectPath: string): Promise<string[]>;
+export interface ImportExternalTemplateOptions {
+    ownsProjectDir?: boolean;
+}
+export declare function cleanupFailedImport(projectPath: string, ownsProjectDir: boolean, preExistingEntries: string[]): Promise<void>;
 export declare function importExternalTemplate(projectPath: string, projectName: string, template: string, logger: {
     log(...args: unknown[]): void;
     error(...args: unknown[]): void;
-}): Promise<TemplateProvenance>;
+}, options?: ImportExternalTemplateOptions): Promise<TemplateProvenance>;

package/dist/test-template-javascript/.extension-create.json

@@ -1,5 +1,5 @@
 {
-  "createdWith": "extension-create@4.0.24",
+  "createdWith": "extension-create@4.0.26",
   "template": "javascript",
   "source": "bundled"
 }

package/dist/test-template-javascript/README.md

@@ -23,7 +23,7 @@ pnpm run dev -- --browser=edge
 Build for production. Convenience scripts target each browser:
 
 ```bash
-pnpm run build           # Chrome (default)
+pnpm run build           # Chromium (default)
 pnpm run build:firefox
 pnpm run build:edge
 ```

package/dist/test-template-javascript/STORE.md

@@ -9,7 +9,7 @@ Packaging your extension is local and free. Submitting the result to a
 store is what [extension.dev](https://docs.extension.dev/publish/overview?utm_source=store-md)
 does, and it sponsors Extension.js.
 
-Last updated: 2026-07-30
+Last updated: 2026-08-02
 
 ## Listing
 

package/dist/test-template-javascript/package.json

@@ -16,7 +16,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "extension": "^4.0.24"
+    "extension": "^4.0.26"
   },
   "packageManager": "pnpm@10.28.0",
   "pnpm": {

package/package.json

@@ -25,7 +25,7 @@
     "templates"
   ],
   "name": "extension-create",
-  "version": "4.0.25",
+  "version": "4.0.27",
   "description": "The standalone extension creation engine for Extension.js",
   "author": {
     "name": "Cezar Augusto",

package/templates/javascript/README.md

@@ -1,7 +1,7 @@
 [powered-image]: https://img.shields.io/badge/Powered%20by-Extension.js-0971fe
 [powered-url]: https://extension.js.org
 
-[![Powered by Extension.js][powered-image]][powered-url]
+![Powered by Extension.js][powered-image]
 
 # JavaScript Starter Extension
 
@@ -47,25 +47,27 @@ src/
 
 ## Commands
 
+Cloned this repo instead? The examples ship without npm scripts, so run Extension.js directly from the example directory. Run `npm install` first when the example declares dependencies.
+
 ### dev
 
 Run the extension in development mode. Target a browser with `--browser`:
 
 ```bash
-npm run dev                 # Chromium (default)
-npm run dev -- --browser=chrome
-npm run dev -- --browser=edge
-npm run dev -- --browser=firefox
+npx extension@latest dev .                  # Chromium (default)
+npx extension@latest dev . --browser=chrome
+npx extension@latest dev . --browser=edge
+npx extension@latest dev . --browser=firefox
 ```
 
 ### build
 
-Build for production. Convenience scripts cover each browser:
+Build for production:
 
 ```bash
-npm run build           # Chrome (default)
-npm run build:firefox
-npm run build:edge
+npx extension@latest build .                # Chromium (default)
+npx extension@latest build . --browser=firefox
+npx extension@latest build . --browser=edge
 ```
 
 ### preview
@@ -73,7 +75,7 @@ npm run build:edge
 Preview the production build with the bundled browser:
 
 ```bash
-npm run preview
+npx extension@latest preview .
 ```
 
 ## Tests