@i-santos/firestack 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## Unreleased
+
+- `firestack test`: added deterministic Functions env parity for test processes.
+  - Firestack now resolves Functions env files per module using:
+    1. `<functions.source>/.env`
+    2. `<functions.source>/.env.<GCLOUD_PROJECT>`
+    3. `<functions.source>/.env.local`
+  - The same merged result is injected into spawned test commands (integration/e2e/ci, docker and non-docker), reducing mismatches between test process env and Functions runtime env.

package/README.md

@@ -0,0 +1,225 @@
+# FireStack (Standalone)
+
+CLI para bootstrap e execução de testes/env em projetos Firebase sem copiar scripts para o repositório do app.
+
+## Modelo Híbrido
+
+Comandos principais:
+
+```bash
+npx firestack install
+npx firestack init
+npx firestack docker init
+npx firestack env --development
+npx firestack test --ci
+npx firestack test --ci --docker --docker-rebuild
+```
+
+### `install`
+
+- cria `firestack.config.json` e `playwright.config.mjs` (se não existirem)
+- adiciona `@playwright/test` em `devDependencies`
+- roda `npm install`
+- roda `playwright install chromium`
+
+### `init`
+
+Cria `firestack.config.json`, `playwright.config.mjs`, `tests/Dockerfile` e `.dockerignore` no projeto alvo.
+O template organiza tudo de teste em `out/tests/...`:
+
+- `out/tests/unit`
+- `out/tests/integration`
+- `out/tests/e2e` (inclui `html/`, `junit.xml` e `artifacts/`)
+
+### `docker init`
+
+Cria (ou atualiza com `--force`) o `tests/Dockerfile` e `.dockerignore` padrão do FireStack no projeto alvo.
+
+### `config migrate`
+
+Aplica migrações pontuais no `firestack.config.json` por chave estável de migração.
+
+Exemplos:
+
+```bash
+npx firestack config migrate --migration integration-spec-default
+npx firestack config migrate --migration integration-spec-default --dry-run
+```
+
+Na migração `integration-spec-default`, o Firestack ajusta `test.commands.integration` (e segmentos legados de integração em `ci`/`ciFailFast`) para usar o runner interno de integração padrão.
+
+### `env`
+
+Gera arquivos `.env` a partir dos templates embutidos no pacote, usando `firestack.config.json`.
+Quando existe `.firebaserc`, os aliases em `projects` são usados como perfis de ambiente.
+
+Exemplos:
+
+```bash
+npx firestack env --profile default
+npx firestack env --development
+npx firestack env --staging --production
+npx firestack env --all --force
+```
+
+Mapeamento padrão por ambiente:
+
+- `default` -> `.env.default` e `.env.test.default`
+- `staging` -> `.env.staging` e `.env.test.staging`
+- `production` -> `.env.production` e `.env.test.production`
+
+No `--all`, o FireStack prioriza aliases de `.firebaserc` (ex.: `default`, `staging`, `production`) e aplica fallback para perfis do `firestack.config.json` quando `.firebaserc` não existe.
+
+### `test`
+
+Executa suites usando comandos definidos em `firestack.config.json`.
+
+Resolução de perfil/projeto/config Firebase para testes:
+
+1. Resolve `profile` por `--profile <alias>`, senão usa `staging` quando `--staging`, senão `FIREBASE_ALIAS`, senão `default`.
+2. Carrega `.env` com fallback por perfil: `.env`, `.env.test`, `.env.<profile>`, `.env.test.<profile>` (para `default`, também considera `development`).
+3. Usa `GCLOUD_PROJECT` se estiver definido; senão resolve de `.firebaserc` pelo alias do profile.
+4. Resolve config Firebase por `--firebase-config <path>`; se não vier, tenta `firebase.<profile>.json` e depois `firebase.json`.
+5. Injeta no processo de testes o mesmo contexto efetivo de env de Cloud Functions (por módulo `functions.source`): `<source>/.env` -> `<source>/.env.<GCLOUD_PROJECT>` -> `<source>/.env.local` (último vence).
+
+Quando o fallback do `.firebaserc` é usado, o CLI também define `FIREBASE_PROJECT_ALIAS` no ambiente (incluindo execução com `--docker`).
+No modo `--docker`, as variáveis resolvidas de Functions também são propagadas para o container de testes.
+
+Exemplos:
+
+```bash
+npx firestack test
+npx firestack test --ci --docker
+npx firestack test --ci --docker --docker-rebuild
+npx firestack test --ci --fail-fast
+npx firestack test --ci --infra-logs compact
+npx firestack test --ci --infra-logs verbose
+npx firestack test --ci --no-log-routing
+npx firestack test --unit
+npx firestack test --integration
+npx firestack test --integration --profile default
+npx firestack test --staging --profile staging --firebase-config firebase.staging.json
+npx firestack test --e2e --full
+npx firestack test --staging --full --docker
+```
+
+No `--ci`, o padrão é executar `integration` e `e2e smoke` e falhar só no final se qualquer suite falhar.
+Para modo fail-fast, use `--fail-fast`.
+
+Roteamento de logs para melhor DX (padrão ativo):
+
+- `--infra-logs compact`: mantém output de testes no terminal e reduz ruído dos emuladores.
+- `--infra-logs verbose`: mostra tudo (comportamento tradicional).
+- `--infra-logs quiet`: mostra só infra importante (warnings/errors) no terminal.
+- `--infra-log-file <path>`: define destino do log completo de infra (default `out/tests/infra/emulator.log`).
+- `--suite-log-file <path>`: define destino do log de suites (default `out/tests/suite/output.log`).
+- por padrão, os arquivos de log são resetados a cada execução.
+- `--log-append`: acumula logs entre execuções (append).
+- `--no-log-routing`: desativa roteamento e mantém stdout original sem filtro.
+
+## Docker (Imagem + Rebuild Inteligente)
+
+Configure no `firestack.config.json`:
+
+```json
+{
+  "test": {
+    "docker": {
+      "dockerfile": "tests/Dockerfile",
+      "imageBaseName": "firestack-tests",
+      "nodeModulesVolumePrefix": "firestack-node_modules-",
+      "functionsNodeModulesVolumePrefix": "firestack-functions-node_modules-",
+      "emulatorCacheVolumePrefix": "firestack-firebase-cache-",
+      "buildNetwork": "host",
+      "bootstrapCommand": "if [ ! -d /work/node_modules/.bin ]; then mkdir -p /work/node_modules && cp -a /opt/deps/node_modules/. /work/node_modules/; fi && if [ -n \"${FIRESTACK_FUNCTIONS_PATHS:-}\" ]; then IFS=',' read -r -a firestack_functions <<< \"$FIRESTACK_FUNCTIONS_PATHS\"; for rel in \"${firestack_functions[@]}\"; do if [ -n \"$rel\" ] && [ -d \"/opt/deps/$rel/node_modules\" ] && [ -f \"/work/$rel/package.json\" ] && [ ! -d \"/work/$rel/node_modules/.bin\" ]; then mkdir -p \"/work/$rel/node_modules\" && cp -a \"/opt/deps/$rel/node_modules/.\" \"/work/$rel/node_modules/\"; fi; done; fi",
+      "runAsHostUser": true,
+      "preloadFirestoreEmulator": true,
+      "writablePaths": ["out"],
+      "addHosts": ["host.docker.internal:host-gateway"],
+      "registry": {
+        "defaultHostUrl": "http://127.0.0.1:4873",
+        "defaultDockerUrl": "http://host.docker.internal:4873"
+      }
+    }
+  }
+}
+```
+
+No modo `--docker`, o FireStack:
+
+- detecta módulos Cloud Functions automaticamente via config Firebase resolvida (`--firebase-config` ou fallback de profile; `functions.source`, incluindo múltiplos codebases);
+- builda imagem com tag baseada em hash de `Dockerfile` + lockfiles + deps de `package.json` (raiz + módulos Functions detectados);
+- reutiliza imagem/volume quando o hash não muda;
+- faz rebuild automático quando deps mudam;
+- monta `node_modules` em volume dedicado por hash para acelerar as execuções.
+- monta `<functions.source>/node_modules` em volume dedicado por hash para cada módulo detectado.
+- mantém cache persistente dos emulators Firebase em volume Docker dedicado e prioriza seed do cache a partir da imagem.
+
+Para forçar rebuild manual da imagem:
+
+```bash
+npx firestack test --ci --docker --docker-rebuild
+```
+
+Guards compatíveis com os scripts legados:
+
+- `ci --docker` bloqueia `E2E_BASE_URL` externo (a menos de `ALLOW_NON_STAGING_E2E=true`);
+- `e2e --docker` valida host permitido para `E2E_BASE_URL`;
+- `staging --docker` valida `GCLOUD_PROJECT` e host staging.
+- por padrão, `GCLOUD_PROJECT` é resolvido de `.firebaserc` (ou de env se já definido). Se quiser travar staging em um projeto específico, configure `test.docker.stagingProjectId`.
+
+`runAsHostUser: true` mantém escrita no bind mount com UID/GID do host.
+Para lockfiles com pacotes em registry local (`127.0.0.1`), use `buildNetwork: "host"` no Linux para o `npm ci` do build enxergar o Verdaccio do host.
+`writablePaths` define diretórios no bind mount que o runner prepara com permissão de escrita para gerar artefatos.
+Para E2E, o FireStack também detecta caminhos locais de output no `playwright.config.*` e libera escrita automaticamente.
+
+Layout recomendado de artefatos (centralizado):
+
+- `out/tests/unit/junit.xml`
+- `out/tests/integration/serial.junit.xml`
+- `out/tests/integration/parallel.junit.xml`
+- `out/tests/integration/junit.xml`
+- `out/tests/e2e/junit.xml`
+- `out/tests/e2e/html/`
+- `out/tests/e2e/artifacts/`
+- `out/tests/e2e/staging/junit.xml`
+- `out/tests/e2e/staging/html/`
+- `out/tests/e2e/staging/artifacts/`
+
+O comando `firestack test` também imprime um resumo final consolidado (unit/integration/e2e) com totais e falhas principais.
+
+## Release (Changesets-only)
+
+O Firestack usa o fluxo padrao do `package-starter`, baseado em Changesets.
+
+Comandos oficiais:
+
+```bash
+npm run check
+npm run changeset
+npm run version-packages
+npm run release
+```
+
+Fluxo de release:
+
+1. Crie um changeset na sua PR (`npm run changeset`).
+2. Faça merge na branch `main`.
+3. O workflow `.github/workflows/release.yml` cria/atualiza a PR `chore: release packages`.
+4. Ao fazer merge dessa PR de release, o publish no npm e executado.
+
+### Bootstrap de projeto existente
+
+Para aplicar esse padrao em um pacote npm ja existente:
+
+```bash
+npx @i-santos/create-package-starter init --dir .
+```
+
+### Pre-requisitos de publicacao
+
+- Configure npm Trusted Publishing para este pacote com:
+- owner/repo: `i-santos/firestack`
+- workflow: `.github/workflows/release.yml`
+- branch: `main`
+- Se `main` for protegida e exigir checks na release PR, configure o secret `CHANGESETS_GH_TOKEN`.

package/bin/firestack.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { runInstall } from '../scripts/cli/install.mjs';
+import { runInit } from '../scripts/cli/init.mjs';
+import { runDockerInit } from '../scripts/cli/docker-init.mjs';
+import { runConfigMigrate } from '../scripts/cli/config-migrate.mjs';
+import { runEnv } from '../scripts/cli/env.mjs';
+import { runTest } from '../scripts/cli/test.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = dirname(__dirname);
+const pkgPath = join(root, 'package.json');
+
+function printHelp() {
+  console.log(`FireStack CLI
+
+Usage:
+  firestack install [--target <dir>] [--dry-run] [--force]
+  firestack init [--target <dir>] [--dry-run] [--force]
+  firestack docker init [--target <dir>] [--dry-run] [--force]
+  firestack config migrate --migration <key> [--target <dir>] [--config <path>] [--dry-run]
+  firestack env [--development|--staging|--production|--all] [--force] [--target <dir>] [--config <path>]
+  firestack test [--ci|--unit|--integration|--e2e|--staging] [--docker] [--docker-rebuild] [--fail-fast] [--full] [--target <dir>] [--config <path>]
+  firestack version
+  firestack help`);
+}
+
+function runInternal(rest) {
+  const [internalCommand, ...internalArgs] = rest;
+  const internalScriptMap = {
+    'run-integration-report': join(root, 'scripts', 'cli', 'internal-run-integration-report.mjs'),
+    'run-functions-build': join(root, 'scripts', 'cli', 'internal-run-functions-build.mjs'),
+    'run-e2e': join(root, 'scripts', 'cli', 'internal-run-e2e.mjs'),
+    'run-e2e-staging': join(root, 'scripts', 'cli', 'internal-run-e2e-staging.mjs'),
+  };
+
+  const scriptPath = internalScriptMap[internalCommand];
+  if (!scriptPath) {
+    console.error(`[firestack] unknown internal command: ${internalCommand ?? '(empty)'}`);
+    process.exit(1);
+  }
+
+  const result = spawnSync(process.execPath, [scriptPath, ...internalArgs], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  if (result.error) {
+    console.error(`[firestack] failed to run internal command "${internalCommand}": ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 1);
+}
+
+function printVersion() {
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  console.log(pkg.version);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === 'version' || command === '--version' || command === '-v') {
+  printVersion();
+  process.exit(0);
+}
+
+if (command === 'install') {
+  runInstall(rest);
+  process.exit(0);
+}
+
+if (command === 'init') {
+  runInit(rest);
+  process.exit(0);
+}
+
+if (command === 'env') {
+  runEnv(rest);
+  process.exit(0);
+}
+
+if (command === 'docker') {
+  const [dockerCommand, ...dockerArgs] = rest;
+  if (dockerCommand === 'init') {
+    runDockerInit(dockerArgs);
+    process.exit(0);
+  }
+  console.error(`[firestack] unknown docker command: ${dockerCommand ?? '(empty)'}`);
+  process.exit(1);
+}
+
+if (command === 'config') {
+  const [configCommand, ...configArgs] = rest;
+  if (configCommand === 'migrate') {
+    runConfigMigrate(configArgs);
+    process.exit(0);
+  }
+  console.error(`[firestack] unknown config command: ${configCommand ?? '(empty)'}`);
+  process.exit(1);
+}
+
+if (command === 'test') {
+  runTest(rest);
+  process.exit(0);
+}
+
+if (command === 'internal') {
+  runInternal(rest);
+  process.exit(0);
+}
+
+console.error(`[firestack] unknown command: ${command}`);
+printHelp();
+process.exit(1);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@i-santos/firestack",
+  "version": "1.0.0",
+  "description": "Portable DX and testing bootstrap for Node/Firebase projects",
+  "type": "module",
+  "private": false,
+  "license": "UNLICENSED",
+  "bin": {
+    "firestack": "bin/firestack.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "scripts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.mjs",
+    "check": "npm run test",
+    "pack": "npm pack",
+    "publish:local": "bash scripts/publish-package.sh",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm run check && changeset publish",
+    "release:ci": "npm run check && npm run version-packages"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^24.10.1",
+    "@changesets/cli": "^2.29.7"
+  }
+}

package/scripts/cli/config-migrate.mjs

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const MIGRATIONS = ['integration-spec-default'];
+
+function printHelp() {
+  console.log(
+    'Usage: firestack config migrate --migration <key> [--target <dir>] [--config <path>] [--dry-run]\n' +
+    `Available migrations: ${MIGRATIONS.join(', ')}`
+  );
+}
+
+function loadConfig(path) {
+  if (!existsSync(path)) {
+    throw new Error(`missing firestack config: ${path}`);
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new Error(`invalid JSON in ${path}`);
+  }
+}
+
+function integrationRunnerCommand() {
+  return 'firestack internal run-functions-build && firebase emulators:exec --project ${GCLOUD_PROJECT:?Set GCLOUD_PROJECT} "firestack internal run-integration-report"';
+}
+
+function applyIntegrationSpecDefault(config) {
+  const next = structuredClone(config);
+  const changes = [];
+
+  next.test = next.test ?? {};
+  next.test.commands = next.test.commands ?? {};
+
+  const currentIntegration = next.test.commands.integration;
+  const desiredIntegration = integrationRunnerCommand();
+  if (currentIntegration !== desiredIntegration) {
+    next.test.commands.integration = desiredIntegration;
+    changes.push('updated test.commands.integration to internal integration runner');
+  }
+
+  const ci = String(next.test.commands.ci ?? '');
+  if (ci && !ci.includes('firestack internal run-integration-report')) {
+    const legacy = /node\s+--test[\s\S]*?tests\/integration\/\*\*\/\*\.test\.ts/g;
+    if (legacy.test(ci)) {
+      next.test.commands.ci = ci.replace(legacy, 'firestack internal run-integration-report');
+      changes.push('updated test.commands.ci integration segment to internal runner');
+    }
+  }
+
+  const ciFailFast = String(next.test.commands.ciFailFast ?? '');
+  if (ciFailFast && !ciFailFast.includes('firestack internal run-integration-report')) {
+    const legacy = /node\s+--test[\s\S]*?tests\/integration\/\*\*\/\*\.test\.ts/g;
+    if (legacy.test(ciFailFast)) {
+      next.test.commands.ciFailFast = ciFailFast.replace(legacy, 'firestack internal run-integration-report');
+      changes.push('updated test.commands.ciFailFast integration segment to internal runner');
+    }
+  }
+
+  return { next, changes };
+}
+
+function runNamedMigration(config, migration) {
+  if (migration === 'integration-spec-default') return applyIntegrationSpecDefault(config);
+  throw new Error(`unsupported --migration "${migration}". available: ${MIGRATIONS.join(', ')}`);
+}
+
+export function runConfigMigrate(argv) {
+  const args = {
+    target: process.cwd(),
+    config: null,
+    dryRun: false,
+    migration: '',
+  };
+
+  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 === '--config') {
+      args.config = resolve(args.target, argv[i + 1] ?? 'firestack.config.json');
+      i += 1;
+      continue;
+    }
+    if (token === '--migration') {
+      args.migration = String(argv[i + 1] ?? '').trim();
+      i += 1;
+      continue;
+    }
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+    if (token === '-h' || token === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+    throw new Error(`unknown argument: ${token}`);
+  }
+
+  if (!args.migration) {
+    throw new Error('missing required argument: --migration <key>');
+  }
+
+  const configPath = args.config ?? resolve(args.target, 'firestack.config.json');
+  const current = loadConfig(configPath);
+  const { next, changes } = runNamedMigration(current, args.migration);
+
+  if (changes.length === 0) {
+    console.log(`[firestack] config already up to date for migration "${args.migration}"`);
+    return;
+  }
+
+  console.log(`[firestack] config migration (${args.migration}) changes:`);
+  for (const change of changes) {
+    console.log(`- ${change}`);
+  }
+
+  if (args.dryRun) {
+    console.log('[firestack] dry-run mode: no file changes written');
+    return;
+  }
+
+  writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  console.log(`[firestack] migrated ${configPath}`);
+}

package/scripts/cli/config.mjs

@@ -0,0 +1,14 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export function loadProjectConfig(cwd, explicitPath = null) {
+  const configPath = explicitPath ?? resolve(cwd, 'firestack.config.json');
+  if (!existsSync(configPath)) {
+    throw new Error(`missing firestack.config.json in ${cwd}. Run: npx firestack init`);
+  }
+  return {
+    path: configPath,
+    data: JSON.parse(readFileSync(configPath, 'utf8')),
+  };
+}
+

package/scripts/cli/docker-init.mjs

@@ -0,0 +1,102 @@
+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_DOCKERFILE = join(ROOT, 'templates', 'tests.Dockerfile');
+const TEMPLATE_DOCKERIGNORE = join(ROOT, 'templates', 'dockerignore');
+
+function printHelp() {
+  console.log('Usage: firestack docker init [--target <dir>] [--force] [--dry-run]');
+}
+
+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 runDockerInit(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_DOCKERFILE, destination: join(args.target, 'tests', 'Dockerfile'), label: 'tests/Dockerfile' },
+  ];
+  let skippedExisting = false;
+
+  for (const file of files) {
+    if (existsSync(file.destination) && !args.force) {
+      console.log(`[firestack] ${file.label} already exists: ${file.destination}`);
+      skippedExisting = true;
+      continue;
+    }
+
+    if (!args.dryRun) {
+      mkdirSync(dirname(file.destination), { recursive: true });
+      cpSync(file.template, file.destination, { recursive: false });
+    }
+    console.log(`[firestack] initialized ${file.destination}`);
+  }
+
+  if (skippedExisting) {
+    console.log('[firestack] use --force to overwrite existing files');
+  }
+  ensureDockerignoreEntries(args.target, args.dryRun);
+
+  if (args.dryRun) {
+    console.log('[firestack] dry-run mode: no files were written');
+  }
+}