jettypod 4.4.118 → 4.4.121

package/apps/dashboard/scripts/download-node.js

@@ -1,104 +0,0 @@
-#!/usr/bin/env node
-/**
- * Downloads Node.js binaries for bundling with the Electron app.
- * Run this before electron-builder to ensure Node.js is available.
- *
- * Usage: node scripts/download-node.js
- */
-
-const https = require('https');
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-
-const NODE_VERSION = 'v24.13.0';  // LTS Krypton
-const ARCHITECTURES = ['arm64', 'x64'];
-const OUTPUT_DIR = path.join(__dirname, '..', 'build-resources', 'node');
-
-function download(url, dest) {
-  return new Promise((resolve, reject) => {
-    const file = fs.createWriteStream(dest);
-    https.get(url, (response) => {
-      if (response.statusCode === 302 || response.statusCode === 301) {
-        // Follow redirect
-        https.get(response.headers.location, (res) => {
-          res.pipe(file);
-          file.on('finish', () => {
-            file.close(resolve);
-          });
-        }).on('error', reject);
-      } else {
-        response.pipe(file);
-        file.on('finish', () => {
-          file.close(resolve);
-        });
-      }
-    }).on('error', reject);
-  });
-}
-
-async function downloadAndExtract(arch) {
-  const archDir = path.join(OUTPUT_DIR, arch);
-  const nodeDir = path.join(archDir, 'bin');
-
-  // Check if already downloaded
-  if (fs.existsSync(path.join(nodeDir, 'node'))) {
-    console.log(`✓ Node.js ${arch} already exists`);
-    return;
-  }
-
-  const tarball = `node-${NODE_VERSION}-darwin-${arch}.tar.gz`;
-  const url = `https://nodejs.org/dist/${NODE_VERSION}/${tarball}`;
-  const tarPath = path.join(OUTPUT_DIR, tarball);
-
-  console.log(`Downloading Node.js ${NODE_VERSION} for ${arch}...`);
-  await download(url, tarPath);
-
-  console.log(`Extracting ${arch}...`);
-  fs.mkdirSync(archDir, { recursive: true });
-  execSync(`tar -xzf "${tarPath}" -C "${OUTPUT_DIR}"`, { stdio: 'inherit' });
-
-  // Move extracted directory to arch name
-  const extractedDir = path.join(OUTPUT_DIR, `node-${NODE_VERSION}-darwin-${arch}`);
-  if (fs.existsSync(archDir)) {
-    fs.rmSync(archDir, { recursive: true });
-  }
-  fs.renameSync(extractedDir, archDir);
-
-  // Remove unnecessary files to reduce size
-  const toRemove = ['include', 'share', 'CHANGELOG.md', 'LICENSE', 'README.md'];
-  for (const item of toRemove) {
-    const itemPath = path.join(archDir, item);
-    if (fs.existsSync(itemPath)) {
-      fs.rmSync(itemPath, { recursive: true });
-    }
-  }
-
-  // Remove corepack (not needed)
-  const corepackBin = path.join(archDir, 'bin', 'corepack');
-  const corepackLib = path.join(archDir, 'lib', 'node_modules', 'corepack');
-  if (fs.existsSync(corepackBin)) fs.rmSync(corepackBin);
-  if (fs.existsSync(corepackLib)) fs.rmSync(corepackLib, { recursive: true });
-
-  // Clean up tarball
-  fs.rmSync(tarPath);
-
-  console.log(`✓ Node.js ${arch} ready`);
-}
-
-async function main() {
-  console.log(`\nPreparing Node.js ${NODE_VERSION} for bundling...\n`);
-
-  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
-
-  for (const arch of ARCHITECTURES) {
-    await downloadAndExtract(arch);
-  }
-
-  console.log('\n✓ All Node.js binaries ready for bundling\n');
-}
-
-main().catch((err) => {
-  console.error('Failed to download Node.js:', err);
-  process.exit(1);
-});

package/apps/dashboard/scripts/upload-to-r2.js

@@ -1,89 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Upload release artifacts to Cloudflare R2.
- * Run after electron-builder: npm run upload:r2
- *
- * Requires CLOUDFLARE_API_TOKEN env var (or wrangler login).
- * Uploads: latest-mac.yml, DMG, ZIP, and blockmap files.
- */
-
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-const BUCKET_NAME = 'jettypod-releases';
-const DIST_DIR = path.join(__dirname, '..', 'dist');
-
-// File patterns to upload
-const UPLOAD_PATTERNS = [
-  /^latest-mac\.yml$/,
-  /\.dmg$/,
-  /\.zip$/,
-  /\.blockmap$/,
-];
-
-function findArtifacts() {
-  if (!fs.existsSync(DIST_DIR)) {
-    console.error(`❌ dist/ directory not found at ${DIST_DIR}`);
-    console.error('Run electron:build first.');
-    process.exit(1);
-  }
-
-  const files = fs.readdirSync(DIST_DIR);
-  return files.filter((file) =>
-    UPLOAD_PATTERNS.some((pattern) => pattern.test(file))
-  );
-}
-
-function uploadFile(filename) {
-  const filePath = path.join(DIST_DIR, filename);
-  const stats = fs.statSync(filePath);
-  const sizeMB = (stats.size / (1024 * 1024)).toFixed(1);
-
-  console.log(`  Uploading ${filename} (${sizeMB} MB)...`);
-
-  try {
-    execSync(
-      `npx wrangler r2 object put "${BUCKET_NAME}/${filename}" --file="${filePath}" --remote`,
-      { stdio: 'pipe' }
-    );
-    console.log(`  ✅ ${filename}`);
-    return true;
-  } catch (error) {
-    console.error(`  ❌ Failed to upload ${filename}: ${error.message}`);
-    return false;
-  }
-}
-
-function main() {
-  console.log('🚀 Uploading release artifacts to R2...\n');
-
-  const artifacts = findArtifacts();
-  if (artifacts.length === 0) {
-    console.error('❌ No release artifacts found in dist/');
-    console.error('Expected: latest-mac.yml, .dmg, .zip, or .blockmap files');
-    process.exit(1);
-  }
-
-  console.log(`Found ${artifacts.length} artifact(s):\n`);
-
-  let success = 0;
-  let failed = 0;
-
-  for (const artifact of artifacts) {
-    if (uploadFile(artifact)) {
-      success++;
-    } else {
-      failed++;
-    }
-  }
-
-  console.log(`\n📦 Upload complete: ${success} uploaded, ${failed} failed`);
-
-  if (failed > 0) {
-    process.exit(1);
-  }
-}
-
-main();

package/docs/bdd-guidance.md

@@ -1,390 +0,0 @@
-What BDD actually is (and isn’t)
-
-BDD is a collaboration + specification technique that uses concrete examples to describe behavior in a shared language.
-
-The “unit tests” are not the point. The examples are the point.
-
-BDD tests should validate behavior that matters to users/business—without leaking implementation details.
-
-BDD ≠ “write all tests in Gherkin.” BDD can be done with plain unit/integration tests too. Gherkin is just a common interface for readability and stakeholder alignment.
-
-A good mental model:
-
-Feature files describe “what” and “why.”
-
-Step definitions implement “how,” but only at a high level.
-
-Lower-level details live in helper layers (Page Objects, API clients, domain helpers).
-
-The BDD flow (what “good” looks like)
-
-Discovery (3 Amigos: product + dev + QA)
-
-Agree on behavior via examples: happy path + edge cases.
-
-Formulation
-
-Turn examples into scenarios (often in Gherkin).
-
-Automation
-
-Implement step definitions that call into a small, reusable automation layer.
-
-Living documentation
-
-Keep scenarios accurate and stable; prune duplicates; version behavior over time.
-
-Gherkin, done well (the style rules that save you later)
-Core primitives
-
-Feature: coherent behavior area
-
-Scenario: one concrete example
-
-Given/When/Then:
-
-Given: preconditions / state
-
-When: action
-
-Then: observable outcomes
-
-Good scenario traits
-
-Small: one behavior, one reason to fail
-
-Declarative: describes intent, not UI clicks
-
-Stable: avoids brittle details (pixel-level UI, timing hacks)
-
-Deterministic: no reliance on “whatever data happens to exist”
-
-Example (good)
-Scenario: User can retry a failed payment
-  Given a user with an unpaid invoice
-  And the payment processor returns "insufficient_funds"
-  When the user retries payment with a different card
-  Then the invoice is marked as paid
-  And the user sees a receipt
-
-Example (brittle / not great)
-Scenario: Pay invoice
-  Given I click the "Billing" tab
-  And I wait 2 seconds
-  And I click the third button on the page
-  When I type "4111111111111111" into the card field
-  Then I should see "Success"
-
-
-This is more of a UI macro recorder than a behavioral spec.
-
-Step definitions: the most common place things go off the rails
-The biggest rule
-
-Step definitions should be thin.
-They should:
-
-parse parameters
-
-call a helper/API/page-object method
-
-assert outcomes at the correct level
-
-They should not:
-
-contain lots of branching logic
-
-do complex loops
-
-embed SQL queries
-
-“know” too much about UI selectors
-
-implement multi-step workflows inline
-
-The “thin step” pattern
-
-Step def → calls one intentful function (e.g., billing.retryPaymentWith(card)), rather than doing click/type/wait directly.
-
-Example structure:
-
-// step definition
-When('the user retries payment with a different card', async () => {
-  await billing.retryPaymentWith(validCard2);
-});
-
-// helper layer (page object / service client)
-async function retryPaymentWith(card) {
-  await openBilling();
-  await selectInvoice(...);
-  await enterCard(card);
-  await submit();
-  await waitForReceipt(); // smart wait, not sleep(2000)
-}
-
-Handling “complex things” in BDD tests (the hard parts)
-1) Asynchrony and eventual consistency
-
-Problem: background jobs, queues, delayed writes, distributed systems.
-
-Best practices
-
-Prefer event-based or state-based polling with timeouts over fixed sleeps.
-
-Assert intermediate states if meaningful (“processing” → “completed”).
-
-If possible, expose a test-only hook (e.g., “job runner runs immediately” in test env).
-
-What to do:
-
-await waitFor(() => order.status === 'COMPLETED', { timeout: 10_000 })
-
-avoid: sleep(5000)
-
-2) External dependencies (payment providers, email/SMS, maps)
-
-Problem: flaky tests, slow runs, rate limits.
-
-Best practices
-
-For most BDD runs: stub at the boundary (in-process fake server, contract stub).
-
-Have a smaller set of true end-to-end smoke tests that hit real external services (maybe nightly).
-
-3) Authentication flows (OAuth, magic links)
-
-Best practices
-
-Prefer test auth shortcuts:
-
-a test-only endpoint to mint tokens
-
-bypass UI login with session injection
-
-Keep one or two UI-login scenarios if you must, but don’t make every scenario pay the “login tax.”
-
-4) Data setup that is “realistic” but not fragile
-
-Problem: complicated prerequisites create scenario bloat.
-
-Best practices
-
-Use factories/fixtures with names that encode intent:
-
-givenUserWithUnpaidInvoice()
-
-givenWorkspaceWith3MembersAndNoAdmin()
-
-Avoid “Given the database has…” in feature files. That’s implementation leakage.
-
-5) Time, randomness, and IDs
-
-Best practices
-
-Freeze time (clock.set("2026-02-10T10:00:00Z")) or inject time providers.
-
-Seed randomness.
-
-Don’t assert on raw IDs; assert on meaning (“receipt exists”, “email sent to user”).
-
-6) UI interactions that are inherently finicky
-
-Best practices
-
-Use stable locators (data-testid, ARIA roles) rather than CSS chains.
-
-Use smart waits (element visible/enabled, network idle) not sleeps.
-
-Put selectors in one place (page objects / screen model).
-
-7) Distributed workflows (webhook in, job runs, UI updates)
-
-Best practices
-
-Split assertions by layer:
-
-API-level scenario verifies webhook → status update
-
-UI-level scenario verifies status display
-
-Don’t force one scenario to validate every link in the chain unless it’s explicitly a top-level acceptance test.
-
-The test pyramid in BDD terms (where each kind of test belongs)
-
-A very effective setup:
-
-Many unit tests (fast, deterministic): pure logic
-
-Many integration/contract tests: service boundaries, DB, message bus (still fast-ish)
-
-Some BDD scenarios: critical user journeys and key edge cases
-
-Very few UI E2E: smoke and “are we totally broken?” checks
-
-BDD scenarios can exist at multiple levels (API-level BDD is often a sweet spot).
-
-Mocks, stubs, fakes: what they are (and why people argue about them)
-Definitions (practical, not academic)
-
-Mock: a test double you can verify interactions with
-(“Was chargeCard() called with amount=4999?”)
-
-Stub: a test double that returns predetermined responses
-(“When /payments is called, return 402 insufficient_funds”)
-
-Fake: a lightweight working implementation
-(in-memory DB, fake email inbox, fake queue)
-
-Spy: like a mock, but wraps a real object and records calls
-
-When to use what
-
-Use stubs/fakes for most BDD scenarios because they support behavior assertions (“user sees receipt”) without coupling to call patterns.
-
-Use mocks sparingly, mostly in unit tests or when verifying a critical side effect is the purpose of the scenario.
-
-The big danger of mocks in BDD
-
-Mocks push you toward testing implementation details:
-
-“did we call X?” rather than “did the user get the outcome?”
-
-Sometimes verifying calls is legitimate (e.g., “audit event emitted”), but generally:
-
-BDD asserts outcomes, not internal choreography.
-
-Step definition best practices checklist (great for “is my AI behaving?”)
-✅ Green flags
-
-Steps are short (often 1–5 lines)
-
-Steps call named helper methods (domain language)
-
-Assertions are in Then steps (or helper assertions)
-
-Givens set up intentful state, not low-level DB edits
-
-Reuse happens through helper methods, not giant shared step defs
-
-Steps avoid sleeps; use smart waits
-
-Scenario language avoids UI specifics unless truly necessary
-
-🚩 Red flags (AI assistants love these)
-
-Step defs contain:
-
-loops, conditionals, try/catch gymnastics
-
-direct SQL / direct ORM writes sprinkled everywhere
-
-lots of selectors + click/type chains inline
-
-random sleeps/timeouts to “make it pass”
-
-Steps are overly generic:
-
-“When I do the thing”
-
-“Then it works”
-
-Heavy parameterization:
-
-Steps with 6–10 parameters usually mean you’re encoding a DSL no one can read
-
-Shared state is global and leaky across scenarios
-
-One scenario validates 12 different outcomes (“kitchen sink test”)
-
-A strict architecture that keeps BDD clean
-
-If you want your AI to stay disciplined, give it a structure it can’t easily “freestyle” out of:
-
-Recommended layers
-
-Feature files (behavior)
-
-Step definitions (glue)
-
-Domain tasks / Screenplay actions (intentful operations)
-
-Drivers
-
-UI driver (page objects / screen model)
-
-API client
-
-DB helper (sparingly)
-
-Message bus helper
-
-Test fixtures/factories
-
-Rule of thumb:
-
-Step defs may depend on domain tasks
-
-Domain tasks may depend on drivers
-
-Feature files know nothing about drivers
-
-This prevents selector soup from infecting Gherkin.
-
-Making your AI assistant “strict” (practical constraints you can enforce)
-
-Here are concrete constraints you can put in your prompt / code review rubric:
-
-Step definition max complexity
-
-No loops
-
-No conditionals except trivial parameter mapping
-
-No sleeps
-
-Selectors forbidden in steps
-
-Must live in page objects/screen models only
-
-One intentful call per step
-
-Steps call one task method
-
-Outcome assertions only in Then
-
-No shared global mutable state
-
-Use scenario context object only
-
-Deterministic data
-
-Factories generate known entities; tests never depend on prod-like ambient data
-
-If you tell the AI “follow best practices,” it’ll nod vigorously and then sleep(2000) anyway. If you tell it “sleep is banned,” it suddenly remembers how to wait for elements like an adult.
-
-Quick example: translating complex behavior into clean steps
-
-Complex behavior: “User triggers export; job runs async; user is notified; file is downloadable.”
-
-Good BDD split:
-
-Scenario asserts user-level behavior
-
-Implementation uses polling and test doubles
-
-Scenario: User can download a completed export
-  Given a user with 3 projects
-  When the user requests a project export
-  Then the export eventually completes
-  And the user can download the export file
-
-
-Implementation strategy:
-
-request export calls API
-
-eventually completes polls status endpoint with timeout
-
-can download checks signed URL returns 200 and file has expected headers
-
-No sleeps, no digging into job queue internals (unless you’re specifically testing that).