@stacksjs/browser-extension 0.70.65

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @stacksjs/browser-extension
+
+Build MV3 browser extensions (Chrome + Firefox) the Stacks way — manifest, content/background scripts, DNR rules, and packaging, all driven by a single `config/extension.ts`.

package/dist/build.d.ts

@@ -0,0 +1,16 @@
+import type { BuildOptions, ExtensionConfig, ExtensionTarget } from './types';
+/** Resolve the output directory for a target. */
+export declare function resolveOutdir(config: ExtensionConfig, target: ExtensionTarget, override?: string): string;
+/**
+ * Build a browser extension for one target: bundle stx pages → HTML, content +
+ * background scripts → classic IIFE bundles, copy static assets, and write the
+ * generated manifest.json. Mirrors the hand-rolled build-extension.ts every
+ * extension used to carry, now driven purely by `ExtensionConfig`.
+ *
+ * The stx page bundling is delegated to `bun-plugin-stx` (loaded lazily so the
+ * package doesn't hard-depend on it when only the manifest/packaging APIs are
+ * used).
+ */
+export declare function buildExtension(config: ExtensionConfig, options: BuildOptions): Promise<{ outdir: string, target: ExtensionTarget }>;
+/** Build every configured target. */
+export declare function buildAllTargets(config: ExtensionConfig, options: Omit<BuildOptions, 'target'>): Promise<void>;

package/dist/build.js

@@ -0,0 +1,64 @@
+import { cp, mkdir, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { contentScriptOut, generateManifest } from "./manifest";
+export function resolveOutdir(config, target, override) {
+  if (override)
+    return override;
+  if (typeof config.outdir === "string")
+    return config.outdir;
+  if (config.outdir?.[target])
+    return config.outdir[target];
+  return target === "firefox" ? "dist-firefox" : "dist";
+}
+export async function buildExtension(config, options) {
+  const target = options.target ?? "chrome", cwd = options.cwd ?? process.cwd(), outdir = resolve(cwd, resolveOutdir(config, target, options.outdir)), minify = options.minify ?? !0;
+  await rm(outdir, { recursive: !0, force: !0 });
+  await mkdir(outdir, { recursive: !0 });
+  if (config.public) {
+    const pub = resolve(cwd, config.public);
+    if (existsSync(pub))
+      await cp(pub, outdir, { recursive: !0 });
+  }
+  const pageEntries = collectPages(config, cwd);
+  if (pageEntries.length) {
+    const { default: stxPlugin } = await import("bun-plugin-stx");
+    await Bun.build({
+      entrypoints: pageEntries,
+      outdir,
+      target: "browser",
+      minify,
+      plugins: [stxPlugin]
+    });
+  }
+  const scripts = [];
+  if (config.background)
+    scripts.push({ entry: config.background, out: "background.js" });
+  for (const cs of config.content ?? [])
+    scripts.push({ entry: cs.entry, out: contentScriptOut(cs.entry, cs.out) });
+  await Promise.all(scripts.map(async ({ entry, out }) => {
+    const result = await Bun.build({
+      entrypoints: [resolve(cwd, entry)],
+      target: "browser",
+      format: "iife",
+      minify
+    });
+    if (!result.success)
+      throw Error(`[browser-extension] failed to build ${entry}: ${result.logs.join(`
+`)}`);
+    await Bun.write(join(outdir, out), await result.outputs[0].text());
+  }));
+  await Bun.write(join(outdir, "manifest.json"), `${JSON.stringify(generateManifest(config, { version: options.version, target }), null, 2)}
+`);
+  return { outdir, target };
+}
+function collectPages(config, cwd) {
+  const p = config.pages;
+  if (!p)
+    return [];
+  return [p.popup, p.options, ...Object.values(p.extra ?? {})].filter(Boolean).map((e) => resolve(cwd, e));
+}
+export async function buildAllTargets(config, options) {
+  for (const target of config.targets ?? ["chrome", "firefox"])
+    await buildExtension(config, { ...options, target });
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+import type { ExtensionConfig } from './types';
+/**
+ * Identity helper for authoring `config/extension.ts` with full type-checking
+ * and editor completion:
+ *
+ * ```ts
+ * // config/extension.ts
+ * import { defineExtension } from '@stacksjs/browser-extension'
+ * export default defineExtension({ name: 'My Extension', description: '…', … })
+ * ```
+ */
+export declare function defineExtension(config: ExtensionConfig): ExtensionConfig;
+/**
+ * Load the project's extension config from `config/extension.ts` (default
+ * export). Returns null when the project has no extension config.
+ */
+export declare function loadExtensionConfig(cwd?: string): Promise<ExtensionConfig | null>;

package/dist/config.js

@@ -0,0 +1,16 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+export function defineExtension(config) {
+  return config;
+}
+export async function loadExtensionConfig(cwd = process.cwd()) {
+  for (const rel of ["config/extension.ts", "extension.config.ts"]) {
+    const path = resolve(cwd, rel);
+    if (!existsSync(path))
+      continue;
+    const mod = await import(path), config = mod.default ?? mod.extension ?? mod.config;
+    if (config)
+      return config;
+  }
+  return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @stacksjs/browser-extension
+ *
+ * Build MV3 browser extensions (Chrome + Firefox) from a single
+ * `ExtensionConfig` — manifest generation, content/background script bundling,
+ * stx pages, declarativeNetRequest rulesets, and store-ready packaging — with
+ * none of the per-project boilerplate.
+ */
+export * from './build';
+export * from './config';
+export * from './manifest';
+export * from './package';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./build";
+export * from "./config";
+export * from "./manifest";
+export * from "./package";
+export * from "./types";

package/dist/manifest.d.ts

@@ -0,0 +1,44 @@
+import type { ExtensionConfig, ExtensionTarget } from './types';
+/** Output filename for a content script (explicit `out`, else entry basename). */
+export declare function contentScriptOut(entry: string, out?: string): string;
+/**
+ * Generate an MV3 manifest for a target from the extension config. Chrome uses
+ * a `service_worker` background + `minimum_chrome_version`; Firefox uses a
+ * `scripts` event page + `browser_specific_settings.gecko` (required by AMO).
+ */
+export declare function generateManifest(config: ExtensionConfig, opts: { version: string, target?: ExtensionTarget }): GeneratedManifest;
+/** MV3 manifest shape (loose — the two targets diverge on `background`). */
+export declare interface GeneratedManifest {
+  manifest_version: 3
+  name: string
+  description: string
+  version: string
+  minimum_chrome_version?: string
+  action?: { default_title?: string, default_popup?: string }
+  options_page?: string
+  background?: { service_worker: string, type?: 'module' } | { scripts: string[], type?: 'module' }
+  browser_specific_settings?: {
+    gecko: {
+      id: string
+      strict_min_version: string
+      data_collection_permissions: { required: ['none'] }
+    }
+  }
+  permissions?: string[]
+  optional_permissions?: string[]
+  host_permissions?: string[]
+  icons?: Record<string, string>
+  content_scripts?: Array<{
+    matches: string[]
+    js: string[]
+    run_at?: string
+    world?: string
+    all_frames?: boolean
+    match_about_blank?: boolean
+    exclude_matches?: string[]
+  }>
+  declarative_net_request?: { rule_resources: Array<{ id: string, enabled: boolean, path: string }> }
+  content_security_policy?: { extension_pages: string }
+  web_accessible_resources?: Array<{ resources: string[], matches: string[] }>
+  [key: string]: unknown
+}

package/dist/manifest.js

@@ -0,0 +1,60 @@
+import { basename } from "node:path";
+export function contentScriptOut(entry, out) {
+  return out ?? basename(entry).replace(/\.[cm]?tsx?$/, ".js");
+}
+export function generateManifest(config, opts) {
+  const isFirefox = (opts.target ?? "chrome") === "firefox", m = config.manifest ?? {}, manifest = {
+    manifest_version: 3,
+    name: config.name,
+    description: config.description,
+    version: opts.version
+  };
+  if (!isFirefox && m.minimumChromeVersion)
+    manifest.minimum_chrome_version = m.minimumChromeVersion;
+  if (config.pages?.popup)
+    manifest.action = { default_title: config.name, default_popup: "popup.html" };
+  if (config.pages?.options)
+    manifest.options_page = "options.html";
+  if (config.background)
+    manifest.background = isFirefox ? { scripts: ["background.js"], type: "module" } : { service_worker: "background.js", type: "module" };
+  if (isFirefox && config.geckoId)
+    manifest.browser_specific_settings = {
+      gecko: {
+        id: config.geckoId,
+        strict_min_version: m.firefoxMinVersion ?? "128.0",
+        data_collection_permissions: { required: ["none"] }
+      }
+    };
+  if (m.permissions?.length)
+    manifest.permissions = m.permissions;
+  if (m.optionalPermissions?.length)
+    manifest.optional_permissions = m.optionalPermissions;
+  if (m.hostPermissions?.length)
+    manifest.host_permissions = m.hostPermissions;
+  if (config.icons)
+    manifest.icons = Object.fromEntries(Object.entries(config.icons).map(([size, path]) => [String(size), path]));
+  if (config.content?.length)
+    manifest.content_scripts = config.content.map((cs) => ({
+      matches: cs.matches,
+      js: [contentScriptOut(cs.entry, cs.out)],
+      ...cs.runAt ? { run_at: cs.runAt } : {},
+      ...cs.world ? { world: cs.world } : {},
+      ...cs.allFrames ? { all_frames: !0 } : {},
+      ...cs.matchAboutBlank ? { match_about_blank: !0 } : {},
+      ...cs.excludeMatches ? { exclude_matches: cs.excludeMatches } : {}
+    }));
+  if (config.rules?.length)
+    manifest.declarative_net_request = {
+      rule_resources: config.rules.map((r) => ({
+        id: r.id,
+        enabled: r.enabled ?? !0,
+        path: r.path ?? `rules/${r.id}.json`
+      }))
+    };
+  manifest.content_security_policy = {
+    extension_pages: m.contentSecurityPolicy ?? "script-src 'self'; object-src 'self'"
+  };
+  if (m.webAccessibleResources?.length)
+    manifest.web_accessible_resources = m.webAccessibleResources;
+  return { ...manifest, ...m.extra ?? {} };
+}

package/dist/package.d.ts

@@ -0,0 +1,15 @@
+import type { ExtensionConfig, ExtensionTarget } from './types';
+/**
+ * Package a built extension into a store-ready `.zip` (one per target). Builds
+ * first unless `build: false`. Uses the system `zip` (available on CI runners
+ * and dev machines) so the archive matches what the Chrome/Firefox stores
+ * expect (files at the archive root, no wrapping directory).
+ */
+export declare function packageExtension(config: ExtensionConfig, options: PackageOptions): Promise<string>;
+export declare interface PackageOptions {
+  target?: ExtensionTarget
+  version: string
+  cwd?: string
+  outfile?: string
+  build?: boolean
+}

package/dist/package.js

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { buildExtension, resolveOutdir } from "./build";
+function slug(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+export async function packageExtension(config, options) {
+  const target = options.target ?? "chrome", cwd = options.cwd ?? process.cwd();
+  if (options.build !== !1)
+    await buildExtension(config, { target, version: options.version, cwd });
+  const outdir = resolve(cwd, resolveOutdir(config, target));
+  if (!existsSync(outdir))
+    throw Error(`[browser-extension] nothing to package: ${outdir} does not exist`);
+  const suffix = target === "firefox" ? "-firefox" : "", outfile = resolve(cwd, options.outfile ?? `${slug(config.name)}-${options.version}${suffix}.zip`);
+  await mkdir(dirname(outfile), { recursive: !0 });
+  const proc = Bun.spawn(["zip", "-r", "-q", outfile, "."], { cwd: outdir, stdout: "pipe", stderr: "pipe" }), code = await proc.exited;
+  if (code !== 0)
+    throw Error(`[browser-extension] zip failed (${code}): ${await new Response(proc.stderr).text()}`);
+  return outfile;
+}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/** A content script mapped into the manifest's `content_scripts`. */
+export declare interface ContentScript {
+  entry: string
+  out?: string
+  matches: string[]
+  runAt?: 'document_start' | 'document_end' | 'document_idle'
+  world?: 'ISOLATED' | 'MAIN'
+  allFrames?: boolean
+  matchAboutBlank?: boolean
+  excludeMatches?: string[]
+}
+/** A declarativeNetRequest static ruleset. */
+export declare interface RuleResource {
+  id: string
+  path?: string
+  enabled?: boolean
+}
+/** An stx page bundled to HTML (popup, options, …). */
+export declare interface ExtensionPages {
+  popup?: string
+  options?: string
+  extra?: Record<string, string>
+}
+/** Overrides merged verbatim into the generated manifest, per target. */
+export declare interface ManifestOverrides {
+  permissions?: string[]
+  hostPermissions?: string[]
+  optionalPermissions?: string[]
+  minimumChromeVersion?: string
+  firefoxMinVersion?: string
+  contentSecurityPolicy?: string
+  webAccessibleResources?: Array<{ resources: string[], matches: string[] }>
+  extra?: Record<string, unknown>
+}
+export declare interface ExtensionConfig {
+  name: string
+  description: string
+  geckoId?: string
+  targets?: ExtensionTarget[]
+  background?: string
+  content?: ContentScript[]
+  pages?: ExtensionPages
+  icons?: Record<number, string>
+  public?: string
+  rules?: RuleResource[]
+  manifest?: ManifestOverrides
+  outdir?: Partial<Record<ExtensionTarget, string>> | string
+}
+export declare interface BuildOptions {
+  target?: ExtensionTarget
+  version: string
+  outdir?: string
+  minify?: boolean
+  cwd?: string
+}
+/**
+ * Config-driven MV3 browser-extension types.
+ *
+ * A consuming app declares one `ExtensionConfig` (typically in
+ * `config/extension.ts` via `defineExtension`) and the framework derives the
+ * manifest, build graph, and packaging from it — no hand-written manifest.json
+ * or per-project build script.
+ */
+export type ExtensionTarget = 'chrome' | 'firefox';

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@stacksjs/browser-extension",
+  "type": "module",
+  "version": "0.70.65",
+  "description": "Build MV3 browser extensions (Chrome + Firefox) the Stacks way — manifest, content/background scripts, DNR rules, packaging, all config-driven.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/browser-extension#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/browser-extension"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "browser-extension",
+    "chrome-extension",
+    "firefox-extension",
+    "manifest-v3",
+    "mv3",
+    "declarativeNetRequest",
+    "bun",
+    "stacks"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "development": "./src/*",
+      "bun": "./dist/*",
+      "import": "./dist/*",
+      "default": "./dist/*"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "better-dx": "^0.2.12"
+  }
+}