@omega.js/extension 0.1.0

package/dist/gulp/tasks/defaults.js

@@ -0,0 +1,281 @@
+// Libraries
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('defaults');
+const watcherLogger = Manager.logger('defaults:watcher');
+const workflowLogger = Manager.logger('defaults:workflows');
+const { watch, series } = require('gulp');
+const jetpack = require('fs-jetpack');
+const path = require('path');
+const { template } = require('node-powertools');
+const { applyDefaults } = require('../../vendor/devkit/defaults-engine.js');
+const { renderSecretsBlock } = require('../../vendor/config/env-delivery.js');
+const { composeTargetWorkflows } = require('../../vendor/devkit/ci-workflows.js');
+
+// Load package
+const package = Manager.getPackage('main');
+const config = Manager.getConfig('project');
+const rootPathPackage = Manager.getRootPath('main');
+
+// Get clean versions — the pinned consumer Node (omega.nodeRuntime), NOT
+// engines.node: engines is the honest dev floor (>=22), templates need a
+// concrete version to render (.nvmrc etc.)
+const cleanVersions = { versions: { ...package.engines, node: package.omega.nodeRuntime } };
+
+// File MAP — rule vocabulary is the devkit defaults engine's (minimatch patterns,
+// last-match-wins). Engine built-ins cover what used to be explicit rules here:
+// `_.` renames (`_.gitignore` → `.gitignore`), `.gitkeep` dir creation, `.DS_Store` skips,
+// and write-only-if-changed.
+const FILE_MAP = {
+  // Files to skip overwrite
+  '**/*.md': {
+    overwrite: false,
+  },
+  'hooks/**/*': {
+    overwrite: false,
+  },
+  'src/**/*': {
+    overwrite: false,
+  },
+  // Consumer-owned after seeding (e.g. test/_init.js fixture hooks) — copy when
+  // missing, never clobber the consumer's version on setup reruns (the engine
+  // fall-through default is overwrite: true)
+  'test/**/*': {
+    overwrite: false,
+  },
+  'src/**/*.{html,md}': {
+    skip: (file) => {
+      // Get the name
+      const name = path.basename(file.name, path.extname(file.name));
+      const htmlFilePath = path.join(file.destination, `${name}.html`);
+      const mdFilePath = path.join(file.destination, `${name}.md`);
+      const htmlFileExists = jetpack.exists(htmlFilePath);
+      const mdFileExists = jetpack.exists(mdFilePath);
+      const eitherExists = htmlFileExists || mdFileExists;
+
+      // Skip if both files exist
+      return eitherExists;
+    },
+  },
+
+  // Marker-section merges (framework owns Default, consumer owns Custom).
+  // The target-root .env is NOT scaffolded ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)):
+  // the brand root's .env is the one file humans and the manager edit, a target
+  // .env is an optional per-key override a HUMAN writes, and no machine writes a
+  // target .env — so the template is gone.
+  '_.gitignore': {
+    mergeLines: true,
+  },
+
+  // The agent-docs chain (#63): AGENTS.md carries the content and uses the same
+  // marker-based merge as .gitignore; CLAUDE.md is the one-line `@AGENTS.md`
+  // pointer, left to the `**/*.md` rule above (copied when missing, never clobbered).
+  // Must come AFTER `**/*.md` (which sets overwrite: false) — last-match-wins,
+  // so this rule's `mergeLines: true` activates the merge path even though the
+  // catch-all would otherwise skip.
+  'AGENTS.md': {
+    mergeLines: true,
+  },
+
+  // Consumer-owned after first seed — the framework-resolving shim
+  // (friction #14); consumers may customize their gulpfile.
+  'gulpfile.js': {
+    overwrite: false,
+  },
+
+  // Config files
+  'config/omega.json5': {
+    overwrite: true,
+    merge: true,
+  },
+  'config/messages.json': {
+    overwrite: false,
+  },
+  'config/description.md': {
+    overwrite: false,
+  },
+
+  // Files to run templating on
+  '.nvmrc': {
+    template: cleanVersions,
+  },
+
+  // Files to skip
+  '**/__temp/**/*': {
+    skip: true,
+  },
+}
+
+// Glob
+const input = [
+  // Files to include
+  `${rootPathPackage}/dist/defaults/**/*`,
+];
+const delay = 250;
+
+// Extensions the global site-token pass applies to — same list (and same
+// `[ site.x ]` bracket syntax) as utils/template-transform.js, which the
+// distribute task still uses as a gulp stream.
+const TEMPLATE_EXTENSIONS = ['html', 'md', 'liquid', 'json', 'yml', 'yaml'];
+
+// The Chrome Web Store caps a listing description at 200 characters.
+const STORE_DESCRIPTION_CAP = 200;
+
+// The store description config/messages.json seeds. `brand.description` is
+// already the one-sentence brand line, so it seeds appDescription whenever it
+// FITS the store cap — every consumer used to hand-edit this one field (#573).
+// Anything longer (or absent) keeps the generic phrasing.
+function resolveAppDescription() {
+  const description = (config.brand?.description || '').trim();
+
+  if (description && description.length <= STORE_DESCRIPTION_CAP) {
+    return description;
+  }
+
+  return `The official ${config.brand?.name || ''} browser extension.`.replace(/\s{2,}/g, ' ');
+}
+
+// Every message the seed renders lands INSIDE a single-quoted JSON5 string, so a
+// value carrying an apostrophe would otherwise leave the scaffolded file
+// unparseable. All four seeded strings — the brand name three of them render, and
+// the description — go through this one escape (#592).
+function escapeSingleQuoted(value) {
+  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\r?\n/g, ' ');
+}
+
+function siteTokenTransform(contents, item) {
+  const ext = path.extname(item.name).toLowerCase().slice(1);
+  if (!TEMPLATE_EXTENSIONS.includes(ext)) {
+    return contents;
+  }
+
+  try {
+    return template(contents, {
+      site: config,
+      versions: cleanVersions.versions,
+      extension: {
+        name: escapeSingleQuoted((config.brand?.name || '').trim()),
+        description: escapeSingleQuoted(resolveAppDescription()),
+      },
+      // The publish workflow's env block is GENERATED from the env schema
+      // ([#627](https://github.com/Omega-JS-Stack/omega/issues/627)) — one
+      // `KEY: ${{ secrets.KEY }}` line per key the schema delivers to the
+      // extension, at the token's two-space indent. The workflow scaffolds with
+      // overwrite: true, so every verb re-renders it from the current schema.
+      githubSecrets: renderSecretsBlock('extension', { indent: '  ' }),
+    }, {
+      brackets: ['[', ']'],
+    });
+  } catch (error) {
+    logger.error(`Error processing templates in ${item.name}:`, error);
+    return contents;
+  }
+}
+
+// Core scaffold — shared devkit engine. Exported for the build-layer scaffold
+// test and the setup command (friction #13: consumers scaffold at setup, and
+// the build's defaults task keeps them synced).
+function scaffoldDefaults(options) {
+  options = options || {};
+  const outputDir = options.outputDir || path.resolve('./');
+
+  // Layer-aware config (cp121c/cp122d): brand targets carry NO local-layer
+  // omega.json5 — the brand file's `targets.*` is the per-target home, and
+  // that file is the STANDALONE escape hatch only. Inside a brand
+  // monorepo the template's config must not scaffold at all (the old
+  // targets-only seed kept resurrecting deleted local files on every setup).
+  const fileMap = { ...FILE_MAP };
+  const { resolveSeedMode } = require('../../vendor/config/index.js');
+  const seed = resolveSeedMode(outputDir);
+  if (!seed.standalone) {
+    fileMap['config/omega.json5'] = { skip: true };
+    // Brand doc unification (Ian 2026-07-20): inside a brand monorepo the
+    // BRAND ROOT is the one doc home — per-target AGENTS.md/CLAUDE.md/CHANGELOG.md/docs/
+    // never scaffold, and existing framework-owned-only copies are swept
+    // (retire rules; consumer content is never destroyed). Standalone projects
+    // keep them. Last-match-wins over the `**/*.md` preserve rule.
+    fileMap['AGENTS.md'] = { retire: true };
+    fileMap['CLAUDE.md'] = { retire: true };
+    fileMap['CHANGELOG.md'] = { retire: true };
+    fileMap['docs/**/*'] = { retire: true };
+    // CI (#265): GitHub runs workflows from the REPO ROOT only, so a per-target
+    // .github/workflows/ in a brand monorepo can never fire. It is composed
+    // into the brand root below instead — scoped to this app's path.
+    fileMap['.github/**/*'] = { skip: true };
+  }
+
+  const result = applyDefaults({
+    defaultsDir: path.join(rootPathPackage, 'dist', 'defaults'),
+    outputDir,
+    files: options.files || null,
+    fileMap,
+    transform: siteTokenTransform,
+    logger,
+  });
+
+  if (!seed.standalone) {
+    composeTargetWorkflows({
+      sourceDir: path.join(rootPathPackage, 'dist', 'defaults', '.github', 'workflows'),
+      targetDir: outputDir,
+      brandRoot: seed.brandRoot,
+      transform: (contents, name) => siteTokenTransform(contents, { name }),
+      logger: workflowLogger,
+    });
+  }
+
+  return result;
+}
+
+// Main task — the LOCAL half of the retired `omega setup` on the gulp lane
+// ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)). A full pass runs
+// ensureTarget (scripts, node check, peer deps, this scaffold, locality), so
+// `npm start` and every gulp build heal the consumer tree on the way past. The
+// watcher's single-file passes re-scaffold that ONE file and nothing else.
+async function defaults(complete, changedFile) {
+  // Log
+  logger.log('Starting...');
+
+  if (changedFile) {
+    scaffoldDefaults({ files: [changedFile] });
+  } else {
+    // Required lazily: ensure-target requires this module back for
+    // scaffoldDefaults, and only one of the two can win at load time.
+    const { ensureTarget } = require('../../commands/lib/ensure-target.js');
+    await ensureTarget({
+      projectDir: Manager.getRootPath('project'),
+      log: (line) => logger.log(line),
+      warn: (line) => logger.warn(line),
+    });
+  }
+
+  // Log
+  logger.log('Finished!');
+
+  // Complete
+  return complete();
+}
+
+function defaultsWatcher(complete) {
+  // Quit if in build mode
+  if (Manager.isBuildMode()) {
+    watcherLogger.log('Skipping watcher in build mode');
+    return complete();
+  }
+
+  // Log
+  watcherLogger.log('Watching for changes...');
+
+  // Watch for changes
+  watch(input, { delay: delay, dot: true })
+  .on('change', (changedPath) => {
+    watcherLogger.log(`File changed (${changedPath})`);
+    // Call defaults with just the changed file
+    defaults(() => {}, changedPath);
+  });
+
+  // Complete
+  return complete();
+}
+
+// Default Task
+module.exports = series(defaults, defaultsWatcher);
+module.exports.scaffoldDefaults = scaffoldDefaults;

package/dist/gulp/tasks/distribute.js

@@ -0,0 +1,172 @@
+// Libraries
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('distribute');
+const fontAwesomeLogger = Manager.logger('distribute:fontawesome');
+const watcherLogger = Manager.logger('distribute:watcher');
+const { src, dest, watch, series } = require('gulp');
+const { Transform } = require('node:stream');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const createTemplateTransform = require('./utils/template-transform');
+
+// Load package
+const package = Manager.getPackage('main');
+const project = Manager.getPackage('project');
+const manifest = Manager.getManifest();
+const config = Manager.getConfig('project');
+const rootPathPackage = Manager.getRootPath('main');
+const rootPathProject = Manager.getRootPath('project');
+
+// Constants
+const LOUD = process.env.OMEGA_LOUD_LOGS === 'true';
+
+// Glob
+const input = [
+  // Files to include
+  'src/**/*',
+
+  // Files to exclude
+  // NOTE: images are NOT excluded — this framework ships no imagemin task, so
+  // excluding them only meant a consumer's static images never reached dist/
+  // and every project copied them by hand from a build:pre hook (#259).
+  // JS files handled by the bundle task
+  '!src/**/*.js',
+  // CSS/SCSS files handled by sass task
+  '!src/**/*.{css,scss,sass}',
+  // HTML files in views handled by html task
+  '!src/views/**/*.html',
+  // Exlcude .DS_Store files
+  '!**/.DS_Store',
+  // Exclude any temp files
+];
+const output = 'dist';
+const delay = 250;
+
+// Index
+let index = -1;
+
+// Copy FontAwesome webfonts from node_modules if installed
+function copyFontAwesomeWebfonts() {
+  const fontAwesomeWebfontsSource = path.resolve(rootPathProject, 'node_modules/@fortawesome/fontawesome-free/webfonts');
+  const fontAwesomeWebfontsDest = path.resolve(rootPathProject, 'dist/assets/webfonts');
+
+  // Check if FontAwesome is installed
+  if (!jetpack.exists(fontAwesomeWebfontsSource)) {
+    fontAwesomeLogger.log('Not installed, skipping webfonts copy');
+    return;
+  }
+
+  // Create destination directory
+  jetpack.dir(fontAwesomeWebfontsDest);
+
+  // Copy .woff2 files
+  const webfontFiles = jetpack.find(fontAwesomeWebfontsSource, { matching: '*.woff2' });
+
+  webfontFiles.forEach(file => {
+    const fileName = path.basename(file);
+    const destPath = path.join(fontAwesomeWebfontsDest, fileName);
+    jetpack.copy(file, destPath, { overwrite: true });
+    fontAwesomeLogger.log(`Copied ${fileName}`);
+  });
+
+  fontAwesomeLogger.log(`Copied ${webfontFiles.length} webfont file(s)`);
+}
+
+// Main task
+function distribute() {
+  return new Promise(async function(resolve, reject) {
+    // Increment index
+    index++;
+
+    // Log
+    logger.log('Starting...');
+
+    // Copy FontAwesome webfonts first
+    copyFontAwesomeWebfonts();
+
+    // Complete
+    return src(input, {
+      base: 'src',
+      dot: true,
+      encoding: false
+    })
+      .pipe(customTransform())
+      .pipe(createTemplateTransform({site: config}))
+      .pipe(dest(output, { encoding: false }))
+      .on('finish', () => {
+        // Log
+        logger.log('Finished!');
+
+        // Complete
+        return resolve();
+      });
+  });
+}
+
+function customTransform() {
+  return new Transform({
+    objectMode: true,
+    transform(file, _, callback) {
+      // Skip if it's a directory
+      if (file.isDirectory()) {
+        return callback(null, file);
+      }
+
+      // Get relative path from src base
+      const relativePath = path.relative(file.base, file.path).replace(/\\/g, '/');
+
+      // Log
+      if (LOUD) {
+        logger.log(`Processing file: ${relativePath}`);
+      }
+
+      // Change path if it starts with 'pages/'
+      // if (relativePath.startsWith('pages/')) {
+      //   // Remove 'pages/' prefix
+      //   const newRelativePath = relativePath.replace(/^pages\//, '');
+
+      //   // Update file path to remove pages directory
+      //   // This will make src/pages/index.html -> dist/index.html
+      //   file.path = path.join(file.base, newRelativePath);
+
+      //   // Log
+      //   logger.log(`  -> Moving from pages/ to root: ${newRelativePath}`);
+      // }
+
+      // Push the file
+      this.push(file);
+
+      // Continue
+      callback();
+    },
+  });
+}
+
+// Watcher task
+function distributeWatcher(complete) {
+  // Quit if in build mode
+  if (Manager.isBuildMode()) {
+    watcherLogger.log('Skipping watcher in build mode');
+    return complete();
+  }
+
+  // Log
+  watcherLogger.log('Watching for changes...');
+
+  // Watch for changes
+  watch(input, { delay: delay, dot: true }, distribute)
+  .on('change', function(path) {
+    watcherLogger.log(`File ${path} was changed`);
+  });
+
+  // Complete
+  return complete();
+}
+
+// Default Task
+module.exports = series(
+  // Manager.wrapTask('distribute', distribute),
+  distribute,
+  distributeWatcher
+);
+module.exports.distribute = distribute;

package/dist/gulp/tasks/fontawesome.js

@@ -0,0 +1,25 @@
+// Libraries
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('fontawesome');
+const { series } = require('gulp');
+const { emitIcons } = require('../../vendor/devkit/icons.js');
+
+// Emit the brand's Font Awesome set (C4 cp112) into dist/assets/icons —
+// the extension-page icon renderer fetches from
+// chrome.runtime.getURL('assets/icons/<style>/<name>.svg'), so the packaged
+// extension carries its icons offline, Pro included when the brand
+// supplies one (OMEGA_FONTAWESOME_ROOT or a fontawesome-pro install).
+// One task run per build — no watcher (the set only changes when the
+// brand's supply does).
+function fontawesome(complete) {
+  const result = emitIcons({ outDir: 'dist' });
+
+  // Log
+  logger.log(`Emitted ${result.files} icons → ${result.dest}`);
+
+  // Complete
+  return complete();
+}
+
+// Default Task
+module.exports = series(fontawesome);

package/dist/gulp/tasks/html.js

@@ -0,0 +1,163 @@
+// Libraries
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('html');
+const watcherLogger = Manager.logger('html:watcher');
+const { src, dest, watch, series } = require('gulp');
+const { Transform } = require('node:stream');
+const jetpack = require('fs-jetpack');
+const path = require('path');
+const { template } = require('node-powertools');
+
+// Load package
+const package = Manager.getPackage('main');
+const project = Manager.getPackage('project');
+const config = Manager.getConfig('project');
+const rootPathPackage = Manager.getRootPath('main');
+const rootPathProject = Manager.getRootPath('project');
+
+// Glob
+const input = [
+  // Files to include
+  'src/views/**/*.html',
+
+  // Files to exclude
+  '!src/views/**/_*.html',
+];
+const output = 'dist/views';
+const delay = 250;
+
+// Main task
+function html(complete) {
+  // Log
+  logger.log('Starting...');
+
+  // Load the template
+  const templatePath = path.join(rootPathPackage, 'dist', 'config', 'page-template.html');
+  const templateContent = jetpack.read(templatePath);
+
+  if (!templateContent) {
+    logger.error('Template not found at:', templatePath);
+    return complete();
+  }
+
+  // Process HTML files
+  return src(input)
+    .pipe(processHtml(templateContent))
+    .pipe(dest(output))
+    .on('finish', () => {
+      logger.log('Finished!');
+      return complete();
+    });
+}
+
+// Process HTML transform
+function processHtml(templateContent) {
+  return new Transform({
+    objectMode: true,
+    transform(file, _, callback) {
+      // Skip if it's a directory
+      if (file.isDirectory()) {
+        return callback(null, file);
+      }
+
+      try {
+        // Get the view name from the file path
+        const viewName = path.basename(file.path, '.html');
+        const relativePath = path.relative(path.join(rootPathProject, 'src/views'), file.dirname);
+        const viewNameWithPath = relativePath ? `${relativePath}/${viewName}` : viewName;
+
+        // Read the content (body HTML)
+        const bodyContent = file.contents.toString();
+
+        // Determine the component name for CSS/JS loading
+        // Template already includes /components/ prefix, so just provide the component path
+        // Pages can have multiple files (index, pricing, login, etc.)
+        // Other components (popup, options, etc.) only have index.html
+        let componentName;
+        if (relativePath.startsWith('pages/') || relativePath === 'pages') {
+          // Pages directory: include full path with filename
+          // pages/index.html -> pages/index
+          // pages/pricing.html -> pages/pricing
+          componentName = viewNameWithPath;
+        } else if (relativePath && viewName === 'index') {
+          // Other components with index.html: use just the directory name
+          // popup/index.html -> popup
+          // options/index.html -> options
+          componentName = relativePath;
+        } else if (relativePath) {
+          // Non-index files in other directories: use full path
+          componentName = viewNameWithPath;
+        } else {
+          // No path: use viewName
+          componentName = viewName;
+        }
+
+        // Prepare template data
+        const data = {
+          content: bodyContent,
+          page: {
+            name: componentName,
+            path: viewNameWithPath,
+            title: config.brand?.name || 'Extension',
+          },
+          theme: {
+            appearance: config.theme?.appearance || 'dark',
+          },
+          brand: config.brand || {},
+          cacheBust: Date.now(),
+        };
+
+        // Apply template with custom brackets
+        // First, template the body content to replace any {{ }} placeholders in the view
+        const templatedBody = template(bodyContent, data, {
+          brackets: ['{{', '}}'],
+        });
+
+        // Update data with templated body
+        data.content = templatedBody;
+
+        // Then template the outer page template
+        const rendered = template(templateContent, data, {
+          brackets: ['{{', '}}'],
+        });
+
+        // Update file contents
+        file.contents = Buffer.from(rendered);
+
+        // Log
+        logger.log(`Processed: ${viewNameWithPath}.html`);
+
+        // Push the file
+        this.push(file);
+        return callback();
+      } catch (error) {
+        logger.error('Error processing HTML:', error);
+        return callback(error);
+      }
+    },
+  });
+}
+
+// Watcher task
+function htmlWatcher(complete) {
+  // Quit if in build mode
+  if (Manager.isBuildMode()) {
+    watcherLogger.log('Skipping watcher in build mode');
+    return complete();
+  }
+
+  // Log
+  watcherLogger.log('Watching for changes...');
+
+  // Watch for changes
+  watch(input, { delay: delay, dot: true }, html)
+    .on('change', function (path) {
+      watcherLogger.log(`File ${path} was changed`);
+    });
+
+  // Complete
+  return complete();
+}
+
+// Export task
+module.exports = series(html, htmlWatcher);