extension 4.0.24 → 4.0.25

package/dist/cli.cjs

@@ -6216,6 +6216,158 @@ var __webpack_modules__ = {
         var external_pintor_ = __webpack_require__("pintor");
         var external_pintor_default = /*#__PURE__*/ __webpack_require__.n(external_pintor_);
         var messaging = __webpack_require__("./helpers/messaging.ts");
+        const DEFAULT_TEMPLATE = "javascript";
+        const TEMPLATE_CATALOG_URL = 'https://github.com/extension-js/examples/tree/main/examples';
+        const TEMPLATE_GROUPS = [
+            {
+                title: 'Starters',
+                summary: 'one language or framework, sidebar UI',
+                templates: [
+                    "javascript",
+                    "typescript",
+                    'react',
+                    'preact',
+                    'vue',
+                    'svelte'
+                ]
+            },
+            {
+                title: 'Sidebar',
+                summary: 'side panel on Chromium, sidebar action on Firefox',
+                templates: [
+                    'sidebar',
+                    'sidebar-antd',
+                    'sidebar-shadcn',
+                    'sidebar-monorepo-turbopack',
+                    'ai-chatgpt',
+                    'ai-claude',
+                    'ai-gemini',
+                    'ai-perplexity',
+                    'playwright',
+                    'transformers-js'
+                ]
+            },
+            {
+                title: "Content scripts",
+                summary: 'code injected into the pages you browse',
+                templates: [
+                    'content',
+                    'content-css-modules',
+                    'content-custom-font',
+                    'content-env',
+                    'content-less',
+                    'content-less-modules',
+                    'content-main-world',
+                    'content-multi-one-entry',
+                    'content-multi-three-entries',
+                    'content-preact',
+                    'content-react',
+                    'content-sass',
+                    'content-sass-modules',
+                    'content-svelte',
+                    "content-typescript",
+                    'content-vue'
+                ]
+            },
+            {
+                title: 'New tab',
+                summary: 'replaces the browser new tab page',
+                templates: [
+                    'new',
+                    'new-browser-flags',
+                    'new-config-eslint',
+                    'new-config-prettier',
+                    'new-config-stylelint',
+                    'new-crypto',
+                    'new-env',
+                    'new-less',
+                    'new-preact',
+                    'new-react',
+                    'new-react-router',
+                    'new-sass',
+                    'new-svelte',
+                    "new-typescript",
+                    'new-vue'
+                ]
+            },
+            {
+                title: 'Toolbar action',
+                summary: 'popup opened from the toolbar button',
+                templates: [
+                    'action',
+                    'action-locales'
+                ]
+            },
+            {
+                title: 'Special folders',
+                summary: "pages/ and scripts/ entrypoints",
+                templates: [
+                    'special-folders-pages',
+                    "special-folders-scripts"
+                ]
+            }
+        ];
+        const TEMPLATE_ALIASES = [
+            {
+                name: 'init',
+                resolvesTo: DEFAULT_TEMPLATE,
+                note: `scaffolds ${DEFAULT_TEMPLATE}, not the catalog folder of the same name`
+            }
+        ];
+        function listTemplates() {
+            return TEMPLATE_GROUPS.flatMap((group)=>group.templates);
+        }
+        function wrapSlugs(slugs, indent, width) {
+            const lines = [];
+            let current = '';
+            for (const slug of slugs){
+                const candidate = current ? `${current}, ${slug}` : slug;
+                if (current && indent.length + candidate.length + 1 > width) {
+                    lines.push(`${indent}${current},`);
+                    current = slug;
+                    continue;
+                }
+                current = candidate;
+            }
+            if (current) lines.push(indent + current);
+            return lines;
+        }
+        function renderTemplateList({ color = true, width = 78 } = {}) {
+            const title = (text)=>color ? external_pintor_default().green(text) : text;
+            const dim = (text)=>color ? external_pintor_default().gray(text) : text;
+            const slug = (text)=>color ? external_pintor_default().blue(text) : text;
+            const lines = [];
+            for (const group of TEMPLATE_GROUPS){
+                lines.push(`  ${title(group.title)} ${dim(`(${group.summary})`)}`);
+                for (const line of wrapSlugs(group.templates, '    ', width))lines.push(slug(line));
+                lines.push('');
+            }
+            lines.push(`  ${title('Aliases')}`);
+            for (const alias of TEMPLATE_ALIASES){
+                lines.push(`    ${slug(alias.name)} ${dim(alias.note)}`);
+                lines.push(dim('      pass its URL to scaffold the catalog folder instead'));
+            }
+            return lines.join('\n');
+        }
+        function renderCreateTemplateHelp() {
+            const total = listTemplates().length;
+            const dim = (text)=>external_pintor_default().gray(text);
+            return [
+                '',
+                external_pintor_default().underline(external_pintor_default().blue(`Templates (${total})`)),
+                renderTemplateList(),
+                '',
+                `  ${external_pintor_default().green('Default')}`,
+                `    ${external_pintor_default().blue(DEFAULT_TEMPLATE)} ${dim('is used when --template is omitted. It ships inside the CLI,')}`,
+                dim('    so it scaffolds with no network call.'),
+                '',
+                `  ${external_pintor_default().green('Everything else')}`,
+                dim('    downloads the catalog archive at create time, so it needs the'),
+                dim('    network and takes longer. A GitHub URL or a ZIP URL also works.'),
+                `    ${external_pintor_default().blue(TEMPLATE_CATALOG_URL)}`,
+                ''
+            ].join('\n');
+        }
         function getLoggingPrefix(type) {
             return (0, messaging.Pl)(type);
         }
@@ -6638,11 +6790,11 @@ Environment variables
 - Example: ${messages_code(messages_arg('EXTENSION_PUBLIC_API_KEY=your_key'))}
 
 Available templates
-- ${external_pintor_default().green('Frameworks')}: ${messages_code(messages_arg('react'))}, ${messages_code(messages_arg('preact'))}, ${messages_code(messages_arg('vue'))}, ${messages_code(messages_arg('svelte'))}
-- ${external_pintor_default().green('Languages')}: ${messages_code(messages_arg("javascript"))}, ${messages_code(messages_arg("typescript"))}
-- ${external_pintor_default().green('Contexts')}: ${messages_code(messages_arg('content'))} (content scripts), ${messages_code(messages_arg('new'))} (new tab), ${messages_code(messages_arg('action'))} (popup)
-- ${external_pintor_default().green('Styling')}: ${messages_code(messages_arg('tailwind'))}, ${messages_code(messages_arg('sass'))}, ${messages_code(messages_arg('less'))}
-- ${external_pintor_default().green('Configs')}: ${messages_code(messages_arg('eslint'))}, ${messages_code(messages_arg('prettier'))}, ${messages_code(messages_arg('stylelint'))}
+${TEMPLATE_GROUPS.map((group)=>`- ${external_pintor_default().green(group.title)} ${messages_arg(`(${group.summary})`)}: ${group.templates.map((template)=>messages_code(template)).join(', ')}`).join('\n')}
+- ${external_pintor_default().green('Alias')}: ${TEMPLATE_ALIASES.map((alias)=>`${messages_code(alias.name)} ${messages_arg(alias.note)}`).join(', ')}
+- ${messages_code(DEFAULT_TEMPLATE)} is the default when ${messages_code('--template')} is omitted. It ships inside the CLI and needs no network.
+- Every other name is downloaded from ${messages_code(TEMPLATE_CATALOG_URL)} at create time. A GitHub or ZIP URL works in place of a name.
+- A name that is not on this list fails with ${messages_code('TemplateNotFoundError')}. Run ${messages_code('extension create --help')} for the same list.
 
 Webpack/Rspack configuration
 - Create ${external_pintor_default().underline(messages_code(messages_arg('extension.config.js')))} for custom webpack configuration
@@ -6774,6 +6926,31 @@ Cross-browser compatibility
                         description: 'Connectable host the browser dials for HMR + the reload bridge when it differs from the bind host (remote/devcontainer)'
                     }
                 ],
+                templates: {
+                    default: DEFAULT_TEMPLATE,
+                    bundled: [
+                        DEFAULT_TEMPLATE
+                    ],
+                    catalogUrl: TEMPLATE_CATALOG_URL,
+                    names: listTemplates(),
+                    groups: TEMPLATE_GROUPS.map((group)=>({
+                            title: group.title,
+                            summary: group.summary,
+                            templates: [
+                                ...group.templates
+                            ]
+                        })),
+                    aliases: TEMPLATE_ALIASES.map((alias)=>({
+                            ...alias
+                        })),
+                    notes: [
+                        `extension create <name> with no --template scaffolds ${DEFAULT_TEMPLATE}`,
+                        `${DEFAULT_TEMPLATE} is bundled with the CLI and scaffolds offline. Every other name downloads the examples archive at create time`,
+                        'a GitHub URL or a ZIP URL is accepted in place of a catalog name',
+                        'a name outside names[] fails with TemplateNotFoundError and creates nothing',
+                        'this list ships with the CLI, so it is the list this CLI version can scaffold, not necessarily the current contents of the catalog repository'
+                    ]
+                },
                 capabilities: {
                     logger: {
                         levels: [
@@ -7444,7 +7621,7 @@ Cross-browser compatibility
             return messaging.Lp.E_INTERNAL;
         }
         function registerCreateCommand(program) {
-            program.command('create').arguments('<project-name|project-path>').usage('<project-name|project-path> [options]').description(commandDescriptions.create).option('-t, --template <template-name>', 'specify a template for the created project').option('--install [boolean]', 'whether or not to install the dependencies after creating the project (disabled by default, pass --install to opt in)', parseOptionalBoolean, false).option('--source <source>', 'attribution tag for where this create was initiated (e.g. cli, templates); recorded in anonymous telemetry only').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').action(async (pathOrRemoteUrl, { template, install, output })=>{
+            program.command('create').arguments('<project-name|project-path>').usage('<project-name|project-path> [options]').description(commandDescriptions.create).option('-t, --template <template-name>', `catalog name, GitHub URL, or ZIP URL to scaffold from; every catalog name is listed below (default: ${DEFAULT_TEMPLATE})`).option('--install [boolean]', 'whether or not to install the dependencies after creating the project (disabled by default, pass --install to opt in)', parseOptionalBoolean, false).option('--source <source>', 'attribution tag for where this create was initiated (e.g. cli, templates); recorded in anonymous telemetry only').option('--output <pretty|json>', 'result format. Use json for a schema-1 envelope on stdout').addHelpText('after', renderCreateTemplateHelp()).action(async (pathOrRemoteUrl, { template, install, output })=>{
                 const asJson = 'json' === output;
                 if (!process.env.EXTENSION_CREATE_DEVELOP_ROOT) try {
                     process.env.EXTENSION_CREATE_DEVELOP_ROOT = resolveExtensionDevelopRoot();
@@ -8633,9 +8810,10 @@ Cross-browser compatibility
             });
         }
         const DEFAULT_API = 'https://www.extension.dev';
+        const PUBLISH_DOCS_URL = 'https://docs.extension.dev/tools/publish';
         function buildPublishRequest(opts) {
             const token = String(opts.token || process.env.EXTENSION_DEV_TOKEN || '').trim();
-            if (!token) throw new Error("No token. Set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard, or via the project access-tokens API) or pass --token.");
+            if (!token) throw new Error(`No token. Publishing needs an extension.dev access token.\nGet one: ${PUBLISH_DOCS_URL}\nThen set EXTENSION_DEV_TOKEN, or pass --token.`);
             const base = String(opts.api || process.env.EXTENSION_DEV_API_URL || DEFAULT_API).replace(/\/+$/, '');
             const body = {};
             if (null != opts.ttl && '' !== opts.ttl) body.ttlHours = Number(opts.ttl);
@@ -8667,7 +8845,7 @@ Cross-browser compatibility
                     await failWith('denied', {
                         code: messaging.Lp.E_AUTH_REQUIRED,
                         message
-                    }, message, 'Set EXTENSION_DEV_TOKEN or pass --token.');
+                    }, message, `Get a token at ${PUBLISH_DOCS_URL}, then set EXTENSION_DEV_TOKEN or pass --token.`);
                     return;
                 }
                 let res;
@@ -8852,6 +9030,7 @@ Cross-browser compatibility
             else obj[key] = value;
             return obj;
         }
+        const VERSION_MAX_LENGTH = 64;
         function sanitizeTag(value) {
             return String(value).trim().replace(/[^a-zA-Z0-9._-]/g, '').slice(0, 64);
         }
@@ -8870,6 +9049,17 @@ Cross-browser compatibility
             const v = process.env;
             return Boolean(v.CI || v.GITHUB_ACTIONS || v.GITLAB_CI || v.BUILDKITE || v.CIRCLECI || v.TRAVIS);
         }
+        const INSTALL_DIRECTORY_MARKERS = [
+            'node_modules',
+            '.pnpm',
+            '.yarn',
+            '.npm',
+            '.bun'
+        ];
+        function isSourceCheckout(startDir = __dirname) {
+            const segments = String(startDir ?? '').split(/[\\/]+/);
+            return !segments.some((segment)=>INSTALL_DIRECTORY_MARKERS.includes(segment));
+        }
         function configDir() {
             const xdg = process.env.XDG_CONFIG_HOME;
             if (xdg) return external_node_path_default().join(xdg, 'extensionjs');
@@ -8973,21 +9163,19 @@ Cross-browser compatibility
                 source: 'env'
             };
             const storage = resolveTelemetryStorage();
-            if (storage) {
-                const stored = readConsentFile(storage.consentFile);
-                if ('enabled' === stored) return {
-                    enabled: true,
-                    source: 'config'
-                };
-                if ('disabled' === stored) return {
-                    enabled: false,
-                    source: 'config'
-                };
-            }
+            const stored = storage ? readConsentFile(storage.consentFile) : null;
+            if ('disabled' === stored) return {
+                enabled: false,
+                source: 'config'
+            };
             if (isCI() && !process.stdout.isTTY) return {
                 enabled: false,
                 source: 'ci'
             };
+            if ('enabled' === stored) return {
+                enabled: true,
+                source: 'config'
+            };
             return {
                 enabled: true,
                 source: 'default'
@@ -9019,7 +9207,7 @@ Cross-browser compatibility
                     const enforcedProps = {
                         command: String(props.command ?? 'unknown').slice(0, 32),
                         success: Boolean(props.success),
-                        version: String(props.version ?? this.version).slice(0, 32)
+                        version: String(props.version ?? this.version).slice(0, VERSION_MAX_LENGTH)
                     };
                     if (props.template) enforcedProps.template = sanitizeTag(props.template);
                     if (props.source) enforcedProps.source = sanitizeTag(props.source);
@@ -9122,7 +9310,8 @@ Cross-browser compatibility
                     os: process.platform,
                     arch: process.arch,
                     node_major: Number(String(process.versions.node).split('.')[0]) || 0,
-                    is_ci: isCI()
+                    is_ci: isCI(),
+                    is_source_build: isSourceCheckout()
                 };
                 if (!this.disabled) {
                     this.storage = resolveTelemetryStorage();

package/dist/extension/helpers/messages.d.ts

@@ -221,6 +221,23 @@ export type ProgramAIHelpJSON = {
         default?: string;
         description: string;
     }>;
+    templates: {
+        default: string;
+        bundled: string[];
+        catalogUrl: string;
+        names: string[];
+        groups: Array<{
+            title: string;
+            summary: string;
+            templates: string[];
+        }>;
+        aliases: Array<{
+            name: string;
+            resolvesTo: string;
+            note: string;
+        }>;
+        notes: string[];
+    };
     capabilities: {
         logger: {
             levels: string[];

package/dist/extension/helpers/telemetry.d.ts

@@ -24,6 +24,7 @@ type TelemetryStorage = {
     consentFile: string;
 };
 export declare const DEFAULT_POSTHOG_KEY: string;
+export declare function isSourceCheckout(startDir?: string): boolean;
 export declare function resolveTelemetryStorage(): TelemetryStorage | null;
 export declare function resolveTelemetryConsent(argv?: string[]): {
     enabled: boolean;

package/dist/extension/helpers/template-catalog.d.ts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_TEMPLATE = "javascript";
+export declare const TEMPLATE_CATALOG_URL = "https://github.com/extension-js/examples/tree/main/examples";
+export interface TemplateGroup {
+    title: string;
+    summary: string;
+    templates: string[];
+}
+export interface TemplateAlias {
+    name: string;
+    resolvesTo: string;
+    note: string;
+}
+export declare const TEMPLATE_GROUPS: readonly TemplateGroup[];
+export declare const TEMPLATE_ALIASES: readonly TemplateAlias[];
+export declare function listTemplates(): string[];
+export declare function templateAliasFor(name: string): TemplateAlias | undefined;
+export interface RenderTemplateListOptions {
+    color?: boolean;
+    width?: number;
+}
+export declare function renderTemplateList({ color, width }?: RenderTemplateListOptions): string;
+export declare function renderCreateTemplateHelp(): string;

package/package.json

@@ -38,7 +38,7 @@
     "extension": "./bin/extension.cjs"
   },
   "name": "extension",
-  "version": "4.0.24",
+  "version": "4.0.25",
   "description": "The cross-browser extension framework. Build Chrome, Edge, Firefox, and Safari extensions with no build configuration.",
   "homepage": "https://extension.js.org/",
   "bugs": {
@@ -106,9 +106,9 @@
     "vivaldi-location2": "2.1.0",
     "waterfox-location": "2.1.0",
     "yandex-location": "2.1.0",
-    "extension-create": "4.0.24",
-    "extension-develop": "4.0.24",
-    "extension-install": "4.0.24",
+    "extension-create": "4.0.25",
+    "extension-develop": "4.0.25",
+    "extension-install": "4.0.25",
     "commander": "^15.0.0",
     "pintor": "0.3.0",
     "semver": "^7.7.3",