@i-santos/firestack 1.0.0

package/scripts/cli/env.mjs

@@ -0,0 +1,168 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadProjectConfig } from './config.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const TEMPLATE_DIR = join(ROOT, 'templates');
+
+function printHelp() {
+  console.log('Usage: firestack env [--profile <alias>] [--development] [--staging] [--production] [--all] [--force] [--target <dir>] [--config <path>]');
+}
+
+function normalizeProfileAlias(name) {
+  const trimmed = String(name ?? '').trim().toLowerCase();
+  if (!trimmed) return '';
+  if (trimmed === 'development') return 'default';
+  return trimmed;
+}
+
+function readFirebaseProjects(targetDir) {
+  const rcPath = resolve(targetDir, '.firebaserc');
+  if (!existsSync(rcPath)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(rcPath, 'utf8'));
+  } catch {
+    throw new Error(`invalid JSON in ${rcPath}`);
+  }
+  const projects = parsed?.projects;
+  if (!projects || typeof projects !== 'object') return {};
+
+  const normalized = {};
+  for (const [alias, projectId] of Object.entries(projects)) {
+    if (typeof projectId !== 'string' || !projectId.trim()) continue;
+    const profileAlias = normalizeProfileAlias(alias);
+    if (!profileAlias) continue;
+    normalized[profileAlias] = projectId.trim();
+  }
+  return normalized;
+}
+
+function resolveFallbackProfiles(configProfiles = {}, firebaseProjects = {}) {
+  const aliasesFromRc = Object.keys(firebaseProjects);
+  if (aliasesFromRc.length > 0) return aliasesFromRc;
+  const aliasesFromConfig = Object.keys(configProfiles).map((name) => normalizeProfileAlias(name)).filter(Boolean);
+  if (aliasesFromConfig.length > 0) return [...new Set(aliasesFromConfig)];
+  return ['default'];
+}
+
+function resolveTemplateVariant(profileAlias) {
+  if (profileAlias === 'staging') return 'staging';
+  if (profileAlias === 'production') return 'production';
+  return 'default';
+}
+
+function buildGeneratedProfile(profileAlias) {
+  const variant = resolveTemplateVariant(profileAlias);
+  const files = [
+    { target: `.env.${profileAlias}`, template: `env/.env.${variant}.example` },
+    { target: `.env.test.${profileAlias}`, template: `env/.env.test.${variant}.example` },
+  ];
+  return { files };
+}
+
+function resolveProfileDefinition(profileAlias, configProfiles) {
+  const explicit = configProfiles[profileAlias];
+  if (explicit && typeof explicit === 'object') return explicit;
+  if (profileAlias === 'default' && configProfiles.development && typeof configProfiles.development === 'object') {
+    return configProfiles.development;
+  }
+  return buildGeneratedProfile(profileAlias);
+}
+
+function upsertProjectId(content, projectId) {
+  if (!projectId) return content;
+  if (/^GCLOUD_PROJECT=.*/m.test(content)) {
+    return content.replace(/^GCLOUD_PROJECT=.*/m, `GCLOUD_PROJECT=${projectId}`);
+  }
+  const prefix = content.endsWith('\n') || content.length === 0 ? '' : '\n';
+  return `${content}${prefix}GCLOUD_PROJECT=${projectId}\n`;
+}
+
+export function runEnv(argv) {
+  const args = {
+    target: process.cwd(),
+    force: false,
+    config: null,
+    all: false,
+    selectedProfiles: new Set(),
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--profile') {
+      const alias = normalizeProfileAlias(argv[i + 1] ?? '');
+      if (!alias) throw new Error('missing value for --profile');
+      args.selectedProfiles.add(alias);
+      i += 1;
+      continue;
+    }
+    if (token === '--development') { args.selectedProfiles.add('default'); continue; }
+    if (token === '--staging') { args.selectedProfiles.add('staging'); continue; }
+    if (token === '--production') { args.selectedProfiles.add('production'); continue; }
+    if (token === '--all') { args.all = true; continue; }
+    if (token === '--target') {
+      args.target = resolve(argv[i + 1] ?? '.');
+      i += 1;
+      continue;
+    }
+    if (token === '--config') {
+      args.config = resolve(argv[i + 1] ?? 'firestack.config.json');
+      i += 1;
+      continue;
+    }
+    if (token === '--force') {
+      args.force = true;
+      continue;
+    }
+    if (token === '-h' || token === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+    throw new Error(`unknown argument: ${token}`);
+  }
+
+  const { data: config } = loadProjectConfig(args.target, args.config);
+  const configProfiles = config.env?.profiles ?? {};
+  const firebaseProjects = readFirebaseProjects(args.target);
+  const fallbackProfiles = resolveFallbackProfiles(configProfiles, firebaseProjects);
+  const selectedProfiles = args.all
+    ? new Set(fallbackProfiles)
+    : (args.selectedProfiles.size > 0 ? args.selectedProfiles : new Set(['default']));
+
+  for (const profileAlias of selectedProfiles) {
+    const profile = resolveProfileDefinition(profileAlias, configProfiles);
+    if (!profile) {
+      throw new Error(`missing env profile "${profileAlias}" in firestack.config.json`);
+    }
+    const mappings = Array.isArray(profile.files) ? profile.files : [];
+    if (mappings.length === 0) {
+      throw new Error(`profile "${profileAlias}" has no files mapping in firestack.config.json`);
+    }
+
+    for (const mapping of mappings) {
+      const targetFile = mapping?.target;
+      const templateFile = mapping?.template;
+      if (!targetFile || !templateFile) {
+        throw new Error(`invalid mapping in profile "${profileName}" (expected target/template)`);
+      }
+
+      const source = join(TEMPLATE_DIR, templateFile);
+      const destination = resolve(args.target, targetFile);
+      if (!existsSync(source)) {
+        throw new Error(`missing template in package: ${templateFile}`);
+      }
+      if (existsSync(destination) && !args.force) {
+        console.log(`[firestack] skipped ${destination} (already exists, use --force to overwrite)`);
+        continue;
+      }
+      mkdirSync(dirname(destination), { recursive: true });
+      const sourceContent = readFileSync(source, 'utf8');
+      const projectId = firebaseProjects[profileAlias] ?? null;
+      const nextContent = upsertProjectId(sourceContent, projectId);
+      writeFileSync(destination, nextContent, 'utf8');
+      console.log(`[firestack] wrote ${destination}`);
+    }
+  }
+}

package/scripts/cli/functions-env.mjs

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export function parseEnvFile(content) {
+  const parsed = {};
+  const lines = String(content).split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const idx = trimmed.indexOf('=');
+    if (idx <= 0) continue;
+    const key = trimmed.slice(0, idx).trim().replace(/^export\s+/, '');
+    let value = trimmed.slice(idx + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\''))) {
+      value = value.slice(1, -1);
+    }
+    parsed[key] = value;
+  }
+  return parsed;
+}
+
+function readJsonStrict(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeRelativePath(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim().replace(/\\/g, '/').replace(/^\.?\//, '');
+  if (!trimmed || trimmed.startsWith('/') || trimmed.includes('..')) return null;
+  return trimmed;
+}
+
+export function discoverFunctionsSourcePaths(cwd, firebaseConfigPath = null) {
+  const configPath = firebaseConfigPath ?? resolve(cwd, 'firebase.json');
+  const firebaseJson = readJsonStrict(configPath);
+  const discovered = [];
+  const addCandidate = (candidate) => {
+    const normalized = normalizeRelativePath(candidate);
+    if (!normalized) return;
+    if (existsSync(resolve(cwd, normalized, 'package.json'))) {
+      discovered.push(normalized);
+    }
+  };
+
+  const functionsConfig = firebaseJson?.functions;
+  if (typeof functionsConfig === 'string') {
+    addCandidate(functionsConfig);
+  } else if (Array.isArray(functionsConfig)) {
+    for (const entry of functionsConfig) {
+      if (typeof entry === 'string') addCandidate(entry);
+      else if (entry && typeof entry === 'object') addCandidate(entry.source);
+    }
+  } else if (functionsConfig && typeof functionsConfig === 'object') {
+    addCandidate(functionsConfig.source);
+  }
+
+  if (discovered.length === 0 && existsSync(resolve(cwd, 'functions', 'package.json'))) {
+    discovered.push('functions');
+  }
+
+  return [...new Set(discovered)];
+}
+
+export function resolveFunctionsRuntimeEnv(cwd, {
+  projectId = null,
+  firebaseConfigPath = null,
+  includeLocal = true,
+} = {}) {
+  const sourcePaths = discoverFunctionsSourcePaths(cwd, firebaseConfigPath);
+  const merged = {};
+  const loadedFiles = [];
+  const normalizedProjectId = typeof projectId === 'string' && projectId.trim() ? projectId.trim() : null;
+
+  for (const sourcePath of sourcePaths) {
+    const candidates = [
+      resolve(cwd, sourcePath, '.env'),
+      ...(normalizedProjectId ? [resolve(cwd, sourcePath, `.env.${normalizedProjectId}`)] : []),
+      ...(includeLocal ? [resolve(cwd, sourcePath, '.env.local')] : []),
+    ];
+
+    for (const filePath of candidates) {
+      if (!existsSync(filePath)) continue;
+      Object.assign(merged, parseEnvFile(readFileSync(filePath, 'utf8')));
+      loadedFiles.push(filePath);
+    }
+  }
+
+  return {
+    env: merged,
+    keys: Object.keys(merged),
+    loadedFiles,
+    sourcePaths,
+  };
+}

package/scripts/cli/init.mjs

@@ -0,0 +1,134 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const TEMPLATE_CONFIG = join(ROOT, 'templates', 'firestack.config.json');
+const TEMPLATE_PLAYWRIGHT_CONFIG = join(ROOT, 'templates', 'playwright.config.mjs');
+const TEMPLATE_DOCKERFILE = join(ROOT, 'templates', 'tests.Dockerfile');
+const TEMPLATE_DOCKERIGNORE = join(ROOT, 'templates', 'dockerignore');
+
+function printHelp() {
+  console.log('Usage: firestack init [--target <dir>] [--force] [--dry-run]');
+}
+
+function ensureOutIgnored(targetDir, dryRun) {
+  const gitignorePath = join(targetDir, '.gitignore');
+  const desiredEntry = 'out/';
+  const hasGitignore = existsSync(gitignorePath);
+  const content = hasGitignore ? readFileSync(gitignorePath, 'utf8') : '';
+  const normalizedLines = content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const alreadyIgnored = normalizedLines.some((line) => line === desiredEntry || line === 'out' || line === '/out/');
+  if (alreadyIgnored) {
+    console.log(`[firestack] .gitignore already contains ${desiredEntry}`);
+    return;
+  }
+
+  if (dryRun) {
+    console.log(`[firestack] would add ${desiredEntry} to ${gitignorePath}`);
+    return;
+  }
+
+  const endsWithNewline = content === '' || content.endsWith('\n');
+  const prefix = content === '' || endsWithNewline ? '' : '\n';
+  const next = `${content}${prefix}${desiredEntry}\n`;
+  writeFileSync(gitignorePath, next, 'utf8');
+  console.log(`[firestack] updated ${gitignorePath} with ${desiredEntry}`);
+}
+
+function ensureDockerignoreEntries(targetDir, dryRun) {
+  const dockerignorePath = join(targetDir, '.dockerignore');
+  const hasDockerignore = existsSync(dockerignorePath);
+  const currentContent = hasDockerignore ? readFileSync(dockerignorePath, 'utf8') : '';
+  const desiredEntries = readFileSync(TEMPLATE_DOCKERIGNORE, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'));
+
+  const existingEntries = new Set(
+    currentContent
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+  );
+  const missing = desiredEntries.filter((entry) => !existingEntries.has(entry));
+  if (missing.length === 0) {
+    console.log('[firestack] .dockerignore already contains default entries');
+    return;
+  }
+
+  if (dryRun) {
+    console.log(`[firestack] would add ${missing.length} entries to ${dockerignorePath}`);
+    return;
+  }
+
+  const endsWithNewline = currentContent === '' || currentContent.endsWith('\n');
+  const prefix = currentContent === '' || endsWithNewline ? '' : '\n';
+  const next = `${currentContent}${prefix}${missing.join('\n')}\n`;
+  writeFileSync(dockerignorePath, next, 'utf8');
+  console.log(`[firestack] updated ${dockerignorePath} with ${missing.length} entries`);
+}
+
+export function runInit(argv) {
+  const args = {
+    target: process.cwd(),
+    force: false,
+    dryRun: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--target') {
+      args.target = resolve(argv[i + 1] ?? '.');
+      i += 1;
+      continue;
+    }
+    if (token === '--force') {
+      args.force = true;
+      continue;
+    }
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+    if (token === '-h' || token === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+    throw new Error(`unknown argument: ${token}`);
+  }
+
+  const files = [
+    { template: TEMPLATE_CONFIG, relativePath: 'firestack.config.json', label: 'firestack.config.json' },
+    { template: TEMPLATE_PLAYWRIGHT_CONFIG, relativePath: 'playwright.config.mjs', label: 'playwright.config.mjs' },
+    { template: TEMPLATE_DOCKERFILE, relativePath: 'tests/Dockerfile', label: 'tests/Dockerfile' },
+  ];
+  let skippedExisting = false;
+
+  for (const file of files) {
+    const destination = join(args.target, file.relativePath);
+    if (existsSync(destination) && !args.force) {
+      console.log(`[firestack] ${file.label} already exists: ${destination}`);
+      skippedExisting = true;
+      continue;
+    }
+    if (!args.dryRun) {
+      mkdirSync(dirname(destination), { recursive: true });
+      cpSync(file.template, destination, { recursive: false });
+    }
+    console.log(`[firestack] initialized ${destination}`);
+  }
+
+  if (skippedExisting) {
+    console.log('[firestack] use --force to overwrite existing files');
+  }
+  ensureDockerignoreEntries(args.target, args.dryRun);
+  ensureOutIgnored(args.target, args.dryRun);
+  if (args.dryRun) {
+    console.log('[firestack] dry-run mode: no files were written');
+  }
+}

package/scripts/cli/install.mjs

@@ -0,0 +1,105 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { runInit } from './init.mjs';
+
+function printHelp() {
+  console.log('Usage: firestack install [--target <dir>] [--force] [--dry-run]');
+}
+
+function mergeDevDependencies(pkg, force, desired) {
+  const existing = pkg.devDependencies ?? {};
+  const merged = { ...existing };
+  const created = [];
+  const skipped = [];
+  const overwritten = [];
+
+  for (const [name, version] of Object.entries(desired)) {
+    if (!(name in merged)) {
+      merged[name] = version;
+      created.push(name);
+      continue;
+    }
+    if (merged[name] === version) continue;
+    if (force) {
+      merged[name] = version;
+      overwritten.push(name);
+    } else {
+      skipped.push(name);
+    }
+  }
+
+  pkg.devDependencies = merged;
+  return { created, skipped, overwritten };
+}
+
+function runInTarget(targetDir, command, args) {
+  const result = spawnSync(command, args, {
+    cwd: targetDir,
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    throw new Error(`failed to execute "${command} ${args.join(' ')}": ${result.error.message}`);
+  }
+  if ((result.status ?? 1) !== 0) {
+    throw new Error(`command failed (${result.status ?? 1}): ${command} ${args.join(' ')}`);
+  }
+}
+
+export function runInstall(argv) {
+  const args = {
+    target: process.cwd(),
+    force: false,
+    dryRun: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--target') {
+      args.target = resolve(argv[i + 1] ?? '.');
+      i += 1;
+      continue;
+    }
+    if (token === '--force') {
+      args.force = true;
+      continue;
+    }
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+    if (token === '-h' || token === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+    throw new Error(`unknown argument: ${token}`);
+  }
+
+  runInit([ '--target', args.target, ...(args.force ? ['--force'] : []), ...(args.dryRun ? ['--dry-run'] : []) ]);
+
+  const pkgPath = join(args.target, 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(`package.json not found in ${args.target}`);
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  const depsResult = mergeDevDependencies(pkg, args.force, {
+    '@playwright/test': '^1.58.2',
+  });
+
+  if (!args.dryRun) {
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+    runInTarget(args.target, 'npm', ['install']);
+    runInTarget(args.target, 'npm', ['exec', 'playwright', 'install', 'chromium']);
+  }
+
+  console.log(`[firestack] devDependencies added: ${depsResult.created.length}`);
+  if (depsResult.overwritten.length > 0) {
+    console.log(`[firestack] devDependencies overwritten: ${depsResult.overwritten.join(', ')}`);
+  }
+  if (depsResult.skipped.length > 0) {
+    console.log(`[firestack] devDependencies skipped (use --force to overwrite): ${depsResult.skipped.join(', ')}`);
+  }
+  if (args.dryRun) {
+    console.log('[firestack] dry-run mode: no files were written');
+  }
+}

package/scripts/cli/internal-e2e-runner.mjs

@@ -0,0 +1,94 @@
+export function resolveSuite(rawSuite) {
+  const suiteArg = (rawSuite ?? 'smoke').trim().toLowerCase();
+  return suiteArg === 'full' ? 'full' : 'smoke';
+}
+
+export function isOverrideAllowed() {
+  return process.env.ALLOW_NON_STAGING_E2E === 'true';
+}
+
+function normalizeHost(rawUrl) {
+  const url = new URL(rawUrl);
+  return url.hostname.toLowerCase();
+}
+
+export function validateExternalBaseUrl(baseUrl, logPrefix) {
+  if (!baseUrl) return;
+  if (isOverrideAllowed()) return;
+
+  let host;
+  try {
+    host = normalizeHost(baseUrl);
+  } catch {
+    throw new Error(`${logPrefix} Invalid E2E_BASE_URL: ${baseUrl}`);
+  }
+
+  const allowedHosts = new Set(['localhost', '127.0.0.1', 'staging.presentgoal.com']);
+  if (!allowedHosts.has(host)) {
+    throw new Error(
+      `${logPrefix} Refusing E2E_BASE_URL host "${host}". Allowed: localhost, 127.0.0.1, staging.presentgoal.com. ` +
+      'Set ALLOW_NON_STAGING_E2E=true to override explicitly.'
+    );
+  }
+}
+
+export function validateStagingBaseUrl(baseUrl, logPrefix) {
+  if (!baseUrl) return;
+  if (isOverrideAllowed()) return;
+
+  let host;
+  try {
+    host = normalizeHost(baseUrl);
+  } catch {
+    throw new Error(`${logPrefix} Invalid E2E_BASE_URL: ${baseUrl}`);
+  }
+
+  if (host !== 'staging.presentgoal.com') {
+    throw new Error(
+      `${logPrefix} Refusing E2E_BASE_URL host "${host}" for staging runner. Allowed only: staging.presentgoal.com. ` +
+      'Set ALLOW_NON_STAGING_E2E=true to override explicitly.'
+    );
+  }
+}
+
+export function grepTagForSuite(suite) {
+  return suite === 'full' ? null : '@smoke';
+}
+
+export function grepInvertTagForSuite() {
+  return '@skip';
+}
+
+export function buildPlaywrightFilterArgs(suite) {
+  const args = [];
+  const grepTag = grepTagForSuite(suite);
+  if (grepTag) {
+    args.push('--grep', grepTag);
+  }
+  const grepInvertTag = grepInvertTagForSuite();
+  if (grepInvertTag) {
+    args.push('--grep-invert', grepInvertTag);
+  }
+  return args;
+}
+
+export function buildRunId(raw) {
+  const value = raw ?? `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return value.replace(/[^a-zA-Z0-9_-]/g, '');
+}
+
+export function requireProject(expectedProjectId, currentProjectId, logPrefix) {
+  if (currentProjectId !== expectedProjectId) {
+    throw new Error(`${logPrefix} Refusing to run with GCLOUD_PROJECT=${currentProjectId}. Expected ${expectedProjectId}.`);
+  }
+  return currentProjectId;
+}
+
+export function resolveStagingCredentials(suite) {
+  const emailVar = suite === 'smoke' ? 'E2E_STAGING_SMOKE_EMAIL' : 'E2E_STAGING_FULL_EMAIL';
+  const passwordVar = suite === 'smoke' ? 'E2E_STAGING_SMOKE_PASSWORD' : 'E2E_STAGING_FULL_PASSWORD';
+  const email = process.env[emailVar] ?? process.env.E2E_STAGING_EMAIL;
+  const password = process.env[passwordVar] ?? process.env.E2E_STAGING_PASSWORD;
+  const useFixedUser = Boolean(email && password);
+  return { emailVar, passwordVar, email, password, useFixedUser };
+}