extension-create 4.0.15 → 4.0.16

package/README.md

@@ -2,8 +2,8 @@
 [npm-version-url]: https://www.npmjs.com/package/extension-create
 [npm-downloads-image]: https://img.shields.io/npm/dm/extension-create.svg?color=0971fe
 [npm-downloads-url]: https://www.npmjs.com/package/extension-create
-[action-image]: https://github.com/extension-js/create/actions/workflows/ci.yml/badge.svg?branch=main
-[action-url]: https://github.com/extension-js/create/actions/workflows/ci.yml
+[action-image]: https://github.com/extension-js/extension.js/actions/workflows/ci.yml/badge.svg?branch=main
+[action-url]: https://github.com/extension-js/extension.js/actions/workflows/ci.yml
 
 [![Version][npm-version-image]][npm-version-url] [![Downloads][npm-downloads-image]][npm-downloads-url] [![CI][action-image]][action-url]
 

package/dist/lib/messages.d.ts

@@ -26,6 +26,8 @@ export declare function writingPackageJsonMetadata(): string;
 export declare function writingPackageJsonMetadataError(projectName: string, error: unknown): string;
 export declare function writingDenoJsonc(): string;
 export declare function writingDenoJsoncError(projectName: string, error: unknown): string;
+export declare function writingTemplateProvenance(): string;
+export declare function writingTemplateProvenanceError(error: unknown): string;
 export declare function writingManifestJsonMetadata(): string;
 export declare function writingManifestJsonMetadataError(projectName: string, error: unknown): string;
 export declare function writingReadmeMetaData(): string;

package/dist/module.cjs

@@ -178,6 +178,12 @@ function writingDenoJsonc() {
 function writingDenoJsoncError(projectName, error) {
     return `${external_pintor_default().red('Error')} Couldn't write ${external_pintor_default().yellow('deno.jsonc')} for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String(error))}\n${external_pintor_default().red('Next step: check file permissions, then try again.')}`;
 }
+function writingTemplateProvenance() {
+    return `${statusPrefix} Writing ${external_pintor_default().yellow('.extension-create.json')}...`;
+}
+function writingTemplateProvenanceError(error) {
+    return `${external_pintor_default().red('Warning')} Couldn't write ${external_pintor_default().yellow('.extension-create.json')} provenance (non-fatal).\n${external_pintor_default().red(String(error))}`;
+}
 function writingManifestJsonMetadata() {
     return `${statusPrefix} Writing ${external_pintor_default().yellow('manifest.json')}...`;
 }
@@ -361,7 +367,22 @@ const NETWORK_TIMEOUT_MS = (()=>{
     const raw = parseInt(String(process.env.EXTENSION_CREATE_TIMEOUT_MS || ''), 10);
     return Number.isFinite(raw) && raw > 0 ? raw : 60000;
 })();
-const EXAMPLES_REF = process.env.EXTENSION_CREATE_TEMPLATE_REF || 'main';
+const CODELOAD_BASE = 'https://codeload.github.com/extension-js/examples/zip';
+function resolveCatalogUrls(ref, overrideUrl) {
+    if (overrideUrl) return [
+        overrideUrl
+    ];
+    if (/^refs\/(heads|tags)\//.test(ref)) return [
+        `${CODELOAD_BASE}/${ref}`
+    ];
+    if (/^[0-9a-f]{40}$/i.test(ref)) return [
+        `${CODELOAD_BASE}/${ref}`
+    ];
+    const urls = [];
+    if (/^[0-9a-f]{7,39}$/i.test(ref)) urls.push(`${CODELOAD_BASE}/${ref}`);
+    urls.push(`${CODELOAD_BASE}/refs/heads/${ref}`, `${CODELOAD_BASE}/refs/tags/${ref}`);
+    return urls;
+}
 class TemplateNotFoundError extends Error {
     constructor(templateName, cause){
         super(`template not found in catalog: ${templateName}`), _define_property(this, "templateName", void 0);
@@ -394,7 +415,10 @@ async function downloadArchive(url, timeoutMs, attempts = 2) {
         return Buffer.from(data);
     } catch (error) {
         lastError = error;
-        if (attempt < attempts) await sleep(400 * attempt);
+        const status = error?.response?.status;
+        const retriable = void 0 === status || 429 === status || status >= 500;
+        if (attempt >= attempts || !retriable) break;
+        await sleep(400 * attempt);
     }
     throw lastError;
 }
@@ -420,14 +444,25 @@ async function extractExamplesTemplateFromZip(zipBuffer, templateName, projectPa
     return written;
 }
 async function importFromExamplesCatalog(templateName, projectPath) {
-    const url = `https://codeload.github.com/extension-js/examples/zip/refs/heads/${EXAMPLES_REF}`;
+    const ref = process.env.EXTENSION_CREATE_TEMPLATE_REF || 'main';
+    const overrideUrl = process.env.EXTENSION_CREATE_TEMPLATE_URL || void 0;
+    const urls = resolveCatalogUrls(ref, overrideUrl);
     let buffer;
-    try {
-        buffer = await downloadArchive(url, NETWORK_TIMEOUT_MS);
+    let source;
+    let lastError;
+    for (const candidate of urls)try {
+        buffer = await downloadArchive(candidate, NETWORK_TIMEOUT_MS);
+        source = candidate;
+        break;
     } catch (error) {
-        throw new TemplateDownloadError(templateName, error);
+        lastError = error;
     }
+    if (!buffer || !source) throw new TemplateDownloadError(templateName, lastError);
     await extractExamplesTemplateFromZip(buffer, templateName, projectPath);
+    return {
+        source,
+        ref: overrideUrl ? void 0 : ref
+    };
 }
 function isAuthorOrDevMode() {
     return 'development' === process.env.EXTENSION_ENV || 'true' === process.env.EXTENSION_AUTHOR_MODE;
@@ -509,7 +544,10 @@ async function importExternalTemplate(projectPath, projectName, template, logger
             if ((0, external_node_fs_namespaceObject.existsSync)(localTemplate)) {
                 await copyDirectoryWithSymlinks(localTemplate, projectPath);
                 await removeTemplateScaffoldingFiles(projectPath);
-                return;
+                return {
+                    template: resolvedTemplateName,
+                    source: 'bundled'
+                };
             }
         }
         const tempRoot = await promises_namespaceObject.mkdtemp(external_node_path_namespaceObject.join(external_node_os_namespaceObject.tmpdir(), 'extension-js-create-'));
@@ -535,6 +573,7 @@ async function importExternalTemplate(projectPath, projectName, template, logger
                 else process.env[k] = v;
             }
         };
+        let provenance;
         if (isGithub) {
             await runGoGitIt(template, tempPath);
             const candidates = await promises_namespaceObject.readdir(tempPath, {
@@ -543,6 +582,10 @@ async function importExternalTemplate(projectPath, projectName, template, logger
             const preferred = candidates.find((d)=>d.isDirectory() && d.name === templateName);
             const srcPath = preferred ? external_node_path_namespaceObject.join(tempPath, templateName) : tempPath;
             await moveDirectoryContents(srcPath, projectPath);
+            provenance = {
+                template: resolvedTemplateName,
+                source: template
+            };
         } else if (isHttp) {
             const { data, headers } = await external_axios_default().get(template, {
                 responseType: 'arraybuffer',
@@ -556,12 +599,26 @@ async function importExternalTemplate(projectPath, projectName, template, logger
             zip.extractAllTo(tempPath, true);
             const sourcePath = await getZipSourcePath(tempPath, template);
             await moveDirectoryContents(sourcePath, projectPath);
-        } else await importFromExamplesCatalog(resolvedTemplateName, projectPath);
+            provenance = {
+                template: resolvedTemplateName,
+                source: template
+            };
+        } else {
+            const catalog = await importFromExamplesCatalog(resolvedTemplateName, projectPath);
+            provenance = {
+                template: resolvedTemplateName,
+                source: catalog.source,
+                ...catalog.ref ? {
+                    ref: catalog.ref
+                } : {}
+            };
+        }
         await removeTemplateScaffoldingFiles(projectPath);
         await promises_namespaceObject.rm(tempRoot, {
             recursive: true,
             force: true
         });
+        return provenance;
     } catch (error) {
         if (error instanceof TemplateNotFoundError) logger.error(templateNotFoundInCatalog(templateName, error.cause));
         else if (error instanceof TemplateDownloadError) logger.error(templateDownloadFailed(templateName, error));
@@ -1439,13 +1496,44 @@ async function writeReadmeFile(projectPath, projectName, logger) {
         throw error;
     }
 }
+const TEMPLATE_PROVENANCE_FILE = '.extension-create.json';
+function ownCreateVersion() {
+    try {
+        const pkg = JSON.parse((0, external_node_fs_namespaceObject.readFileSync)(external_node_path_namespaceObject.join(__dirname, '..', 'package.json'), 'utf8'));
+        return 'string' == typeof pkg.version && pkg.version ? `extension-create@${pkg.version}` : void 0;
+    } catch  {
+        return;
+    }
+}
+function buildProvenanceRecord(provenance) {
+    return {
+        ...ownCreateVersion() ? {
+            createdWith: ownCreateVersion()
+        } : {},
+        template: provenance.template,
+        source: provenance.source,
+        ...provenance.ref ? {
+            ref: provenance.ref
+        } : {}
+    };
+}
+async function writeTemplateProvenance(projectPath, provenance, logger) {
+    if (!provenance?.template) return;
+    const record = buildProvenanceRecord(provenance);
+    try {
+        logger.log(writingTemplateProvenance());
+        await promises_namespaceObject.writeFile(external_node_path_namespaceObject.join(projectPath, TEMPLATE_PROVENANCE_FILE), `${JSON.stringify(record, null, 2)}\n`);
+    } catch (error) {
+        logger.error(writingTemplateProvenanceError(error));
+    }
+}
 async function extensionCreate(projectNameInput, { cliVersion, template = "javascript", install = false, logger = console }) {
     if (!projectNameInput) throw new Error(noProjectName());
     if (projectNameInput.startsWith('http')) throw new Error(noUrlAllowed());
     const projectPath = external_node_path_namespaceObject.isAbsolute(projectNameInput) ? projectNameInput : external_node_path_namespaceObject.join(process.cwd(), projectNameInput);
     const projectName = external_node_path_namespaceObject.basename(projectPath);
     await createDirectory(projectPath, projectName, logger);
-    await importExternalTemplate(projectPath, projectName, template, logger);
+    const templateProvenance = await importExternalTemplate(projectPath, projectName, template, logger);
     const isMonorepoTemplate = String(template).toLowerCase().includes('monorepo');
     if (isDenoRuntime() && !isMonorepoTemplate) await writeDenoJsonc(projectPath, projectName, {
         template,
@@ -1461,6 +1549,7 @@ async function extensionCreate(projectNameInput, { cliVersion, template = "javas
             template
         }, logger);
     }
+    await writeTemplateProvenance(projectPath, templateProvenance, logger);
     if (install) {
         await installDependencies(projectPath, projectName, logger);
         await installInternalDependencies(projectPath, logger);
@@ -1478,7 +1567,8 @@ async function extensionCreate(projectNameInput, { cliVersion, template = "javas
         projectName,
         template,
         depsInstalled: install,
-        packageManager: resolveScaffoldPackageManager()
+        packageManager: resolveScaffoldPackageManager(),
+        templateProvenance
     };
 }
 exports.extensionCreate = __webpack_exports__.extensionCreate;

package/dist/module.d.ts

@@ -1,4 +1,5 @@
 import { type ScaffoldPackageManager } from './lib/package-manager';
+import { type TemplateProvenance } from './steps/import-external-template';
 export interface CreateLogger {
     log: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
@@ -15,5 +16,6 @@ export interface CreateResult {
     template: string;
     depsInstalled: boolean;
     packageManager: ScaffoldPackageManager;
+    templateProvenance: TemplateProvenance;
 }
 export declare function extensionCreate(projectNameInput: string | undefined, { cliVersion, template, install, logger }: CreateOptions): Promise<CreateResult>;

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

@@ -1,3 +1,9 @@
+export declare function resolveCatalogUrls(ref: string, overrideUrl?: string): string[];
+export interface TemplateProvenance {
+    template: string;
+    source: string;
+    ref?: string;
+}
 export declare class TemplateNotFoundError extends Error {
     readonly templateName: string;
     constructor(templateName: string, cause?: unknown);
@@ -12,4 +18,4 @@ export declare function removeTemplateScaffoldingFiles(projectPath: string): Pro
 export declare function importExternalTemplate(projectPath: string, projectName: string, template: string, logger: {
     log(...args: unknown[]): void;
     error(...args: unknown[]): void;
-}): Promise<void>;
+}): Promise<TemplateProvenance>;

package/dist/steps/write-template-provenance.d.ts

@@ -0,0 +1,7 @@
+import type { TemplateProvenance } from './import-external-template';
+export declare const TEMPLATE_PROVENANCE_FILE = ".extension-create.json";
+export declare function buildProvenanceRecord(provenance: TemplateProvenance): Record<string, string>;
+export declare function writeTemplateProvenance(projectPath: string, provenance: TemplateProvenance, logger: {
+    log(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}): Promise<void>;

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

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

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

@@ -21,7 +21,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "extension": "^4.0.14"
+    "extension": "^4.0.15"
   },
   "packageManager": "pnpm@10.28.0",
   "pnpm": {

package/package.json

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