quackdev 0.1.0

package/bin/quack.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import { program } from "commander";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+
+program
+  .name("quack")
+  .description("Zero-config bug detection for your CI")
+  .version(pkg.version, "-v, --version");
+
+program
+  .command("login")
+  .description("Authenticate with your Quack account")
+  .action(async () => {
+    const { login } = await import("../src/commands/login.js");
+    await login();
+  });
+
+program
+  .command("logout")
+  .description("Sign out of your Quack account")
+  .action(async () => {
+    const { logout } = await import("../src/commands/logout.js");
+    await logout();
+  });
+
+program
+  .command("init")
+  .description("Initialize Quack in the current project")
+  .action(async () => {
+    const { init } = await import("../src/commands/init.js");
+    await init();
+  });
+
+program
+  .command("scan")
+  .description("Run a Quack scan on the current project")
+  .option("--ci", "Run in CI mode (non-interactive, exit code reflects results)")
+  .action(async (opts) => {
+    const { scan } = await import("../src/commands/scan.js");
+    await scan({ ci: opts.ci });
+  });
+
+program
+  .command("whoami")
+  .description("Show the currently authenticated user")
+  .action(async () => {
+    const { isAuthenticated, getLogin } = await import("../src/lib/config.js");
+    const { log } = await import("../src/lib/logger.js");
+    log.blank();
+    if (isAuthenticated()) {
+      log.success(`Logged in as ${getLogin() || "(unknown)"}`);
+    } else {
+      log.warn("Not logged in.");
+    }
+    log.blank();
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "quackdev",
+  "version": "0.1.0",
+  "description": "Zero-config bug detection for your CI. Discovers user flows, runs them in a headless browser, and surfaces bugs automatically.",
+  "type": "module",
+  "bin": {
+    "quack": "bin/quack.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "testing",
+    "ci",
+    "e2e",
+    "bug-detection",
+    "quack"
+  ],
+  "author": "Quack",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quackdev/quack.git",
+    "directory": "cli"
+  },
+  "homepage": "https://quack.dev",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "conf": "^13.1.0",
+    "open": "^10.1.2",
+    "ora": "^8.2.0"
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import ora from "ora";
+import { CONFIG_FILE, WORKFLOW_PATH } from "../lib/constants.js";
+import { isAuthenticated, getToken } from "../lib/config.js";
+import { apiPost } from "../lib/api.js";
+import { log } from "../lib/logger.js";
+
+const WORKFLOW_TEMPLATE = `name: Quack Bug Detection
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  quack:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Quack
+        run: npm install -g @luisf_mc/quack
+
+      - name: Run Quack Scan
+        run: quack scan --ci
+        env:
+          QUACK_TOKEN: \${{ secrets.QUACK_TOKEN }}
+`;
+
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (
+      fs.existsSync(path.join(dir, "package.json")) ||
+      fs.existsSync(path.join(dir, ".git"))
+    ) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return startDir;
+}
+
+function detectFramework(projectRoot) {
+  const pkgPath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(pkgPath)) return { name: "unknown", entryPoints: [] };
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  const deps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  };
+
+  if (deps["next"]) return { name: "Next.js", entryPoints: ["/", "/api"] };
+  if (deps["nuxt"]) return { name: "Nuxt", entryPoints: ["/"] };
+  if (deps["@angular/core"]) return { name: "Angular", entryPoints: ["/"] };
+  if (deps["svelte"] || deps["@sveltejs/kit"]) return { name: "SvelteKit", entryPoints: ["/"] };
+  if (deps["react"]) return { name: "React", entryPoints: ["/"] };
+  if (deps["vue"]) return { name: "Vue", entryPoints: ["/"] };
+  if (deps["express"]) return { name: "Express", entryPoints: ["/"] };
+
+  return { name: "unknown", entryPoints: ["/"] };
+}
+
+export async function init() {
+  log.blank();
+  log.brand("  quack init");
+  log.blank();
+
+  if (!isAuthenticated()) {
+    log.error(`Not authenticated. Run ${chalk.cyan("quack login")} first.`);
+    log.blank();
+    process.exit(1);
+  }
+
+  const projectRoot = findProjectRoot(process.cwd());
+  const framework = detectFramework(projectRoot);
+
+  log.step(1, `Detected project at ${chalk.dim(projectRoot)}`);
+  if (framework.name !== "unknown") {
+    log.success(`Framework: ${chalk.bold(framework.name)}`);
+  }
+  log.blank();
+
+  // Write .quack.json config
+  const spinner1 = ora("Creating quack config…").start();
+  const configPath = path.join(projectRoot, CONFIG_FILE);
+
+  const quackConfig = {
+    version: 1,
+    framework: framework.name,
+    entryPoints: framework.entryPoints,
+    ignore: ["node_modules", ".git", "dist", "build", ".next"],
+    headless: true,
+  };
+
+  fs.writeFileSync(configPath, JSON.stringify(quackConfig, null, 2) + "\n");
+  spinner1.succeed(`Created ${chalk.cyan(CONFIG_FILE)}`);
+
+  // Write GitHub Actions workflow
+  const spinner2 = ora("Setting up CI workflow…").start();
+  const workflowFullPath = path.join(projectRoot, WORKFLOW_PATH);
+  const workflowDir = path.dirname(workflowFullPath);
+
+  if (!fs.existsSync(workflowDir)) {
+    fs.mkdirSync(workflowDir, { recursive: true });
+  }
+
+  fs.writeFileSync(workflowFullPath, WORKFLOW_TEMPLATE);
+  spinner2.succeed(`Created ${chalk.cyan(WORKFLOW_PATH)}`);
+
+  // Register project with API (non-blocking — gracefully fails if API is down)
+  const spinner3 = ora("Registering project…").start();
+  try {
+    await apiPost("/projects/register", {
+      root: projectRoot,
+      framework: framework.name,
+      entryPoints: framework.entryPoints,
+    });
+    spinner3.succeed("Project registered with Quack");
+  } catch {
+    spinner3.warn("Could not reach Quack API — project will register on first scan");
+  }
+
+  log.blank();
+  log.success(chalk.bold("You're all set!"));
+  log.blank();
+  log.dim(
+    `Quack will run on every push and PR via GitHub Actions.`
+  );
+  log.dim(
+    `Bugs will surface as check annotations on your commits.`
+  );
+  log.blank();
+  log.info(
+    `Add ${chalk.cyan("QUACK_TOKEN")} to your repo secrets:`
+  );
+  log.dim(
+    `${chalk.dim("→")} Settings → Secrets → Actions → ${chalk.bold("New repository secret")}`
+  );
+  log.dim(
+    `  Name:  ${chalk.bold("QUACK_TOKEN")}`
+  );
+  log.dim(
+    `  Value: ${chalk.hex("#F6AD3C")(getToken().slice(0, 6) + "••••••••")}`
+  );
+  log.blank();
+  log.info(
+    `Or run ${chalk.cyan("quack scan")} to test locally now.`
+  );
+  log.blank();
+}

package/src/commands/login.js

@@ -0,0 +1,61 @@
+import chalk from "chalk";
+import open from "open";
+import ora from "ora";
+import crypto from "node:crypto";
+import { DASHBOARD_URL } from "../lib/constants.js";
+import { setAuth, isAuthenticated, getLogin } from "../lib/config.js";
+import { pollAuth } from "../lib/api.js";
+import { log } from "../lib/logger.js";
+
+export async function login() {
+  log.blank();
+  log.brand("  quack login");
+  log.blank();
+
+  if (isAuthenticated()) {
+    const currentLogin = getLogin();
+    log.success(`Already authenticated${currentLogin ? ` as ${chalk.bold(currentLogin)}` : ""}.`);
+    log.dim(`Run ${chalk.cyan("quack logout")} to sign out first.`);
+    log.blank();
+    return;
+  }
+
+  const sessionId = crypto.randomUUID();
+  const authUrl = `${DASHBOARD_URL}/auth/cli?session=${sessionId}`;
+
+  log.info("Opening your browser to authenticate…");
+  log.dim(chalk.underline(authUrl));
+  log.blank();
+
+  await open(authUrl);
+
+  const spinner = ora({
+    text: "Waiting for authentication…",
+    color: "yellow",
+  }).start();
+
+  try {
+    const data = await pollAuth(sessionId);
+
+    setAuth({
+      token: data.token,
+      userId: data.userId,
+      login: data.login,
+    });
+
+    spinner.succeed(`Authenticated as ${chalk.bold(data.login)}`);
+    log.blank();
+
+    const masked = data.token.slice(0, 6) + "••••••••";
+    log.dim(`Token: ${chalk.hex("#F6AD3C")(masked)}`);
+    log.dim(`Stored in your system keychain.`);
+    log.blank();
+    log.info(`Next, run ${chalk.cyan("quack init")} in your project.`);
+    log.blank();
+  } catch (err) {
+    spinner.fail("Authentication failed.");
+    log.error(err.message);
+    log.blank();
+    process.exit(1);
+  }
+}

package/src/commands/logout.js

@@ -0,0 +1,22 @@
+import chalk from "chalk";
+import { clearAuth, isAuthenticated, getLogin } from "../lib/config.js";
+import { log } from "../lib/logger.js";
+
+export async function logout() {
+  log.blank();
+
+  if (!isAuthenticated()) {
+    log.warn("You're not currently logged in.");
+    log.blank();
+    return;
+  }
+
+  const login = getLogin();
+  clearAuth();
+
+  log.success(
+    `Signed out${login ? ` from ${chalk.bold(login)}` : ""}.`
+  );
+  log.dim(`Run ${chalk.cyan("quack login")} to authenticate again.`);
+  log.blank();
+}

package/src/commands/scan.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import ora from "ora";
+import { CONFIG_FILE } from "../lib/constants.js";
+import { isAuthenticated } from "../lib/config.js";
+import { apiPost } from "../lib/api.js";
+import { log } from "../lib/logger.js";
+
+function loadConfig() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    const configPath = path.join(dir, CONFIG_FILE);
+    if (fs.existsSync(configPath)) {
+      return {
+        root: dir,
+        config: JSON.parse(fs.readFileSync(configPath, "utf-8")),
+      };
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function collectSourceFiles(root, ignore) {
+  const exts = new Set([".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte"]);
+  const results = [];
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const rel = path.relative(root, full);
+
+      if (ignore.some((pattern) => rel.startsWith(pattern))) continue;
+
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (exts.has(path.extname(entry.name))) {
+        results.push(rel);
+      }
+    }
+  }
+
+  walk(root);
+  return results;
+}
+
+export async function scan({ ci = false } = {}) {
+  log.blank();
+  log.brand("  quack scan");
+  log.blank();
+
+  if (!isAuthenticated()) {
+    if (ci && process.env.QUACK_TOKEN) {
+      log.dim("Using QUACK_TOKEN from environment.");
+    } else {
+      log.error(`Not authenticated. Run ${chalk.cyan("quack login")} first.`);
+      log.blank();
+      process.exit(1);
+    }
+  }
+
+  const project = loadConfig();
+  if (!project) {
+    log.error(
+      `No ${chalk.cyan(CONFIG_FILE)} found. Run ${chalk.cyan("quack init")} first.`
+    );
+    log.blank();
+    process.exit(1);
+  }
+
+  const { root, config } = project;
+
+  // Phase 1: Analyze
+  const spinner1 = ora("Analyzing codebase…").start();
+  const files = collectSourceFiles(root, config.ignore || []);
+  spinner1.succeed(
+    `Analyzed ${chalk.bold(files.length)} source files (${chalk.dim(config.framework)})`
+  );
+
+  // Phase 2: Discover flows
+  const spinner2 = ora("Discovering user flows…").start();
+  try {
+    const discovery = await apiPost("/scan/discover", {
+      framework: config.framework,
+      entryPoints: config.entryPoints,
+      files: files.slice(0, 200),
+    });
+
+    const flowCount = discovery.flows?.length || 0;
+    spinner2.succeed(
+      `Discovered ${chalk.bold(flowCount)} user flow${flowCount !== 1 ? "s" : ""}`
+    );
+
+    if (discovery.flows) {
+      for (const flow of discovery.flows) {
+        log.dim(
+          `  ${chalk.hex("#F6AD3C")("→")} ${flow.name} (${flow.entry}, ${flow.steps} steps)`
+        );
+      }
+    }
+
+    log.blank();
+
+    // Phase 3: Generate tests
+    const spinner3 = ora("Generating test cases…").start();
+    const generation = await apiPost("/scan/generate", {
+      flows: discovery.flows,
+    });
+
+    const testCount = generation.tests?.length || 0;
+    spinner3.succeed(
+      `Generated ${chalk.bold(testCount)} test${testCount !== 1 ? "s" : ""}`
+    );
+    log.blank();
+
+    // Phase 4: Run tests
+    const spinner4 = ora("Running tests in headless browser…").start();
+    const results = await apiPost("/scan/run", {
+      tests: generation.tests,
+      headless: config.headless,
+    });
+
+    const passed = results.results?.filter((r) => r.status === "passed").length || 0;
+    const failed = results.results?.filter((r) => r.status === "failed").length || 0;
+
+    if (failed > 0) {
+      spinner4.fail(
+        `${chalk.bold(passed)} passed, ${chalk.red.bold(failed)} failed`
+      );
+    } else {
+      spinner4.succeed(
+        `All ${chalk.bold(passed)} tests passed`
+      );
+    }
+
+    log.blank();
+
+    if (results.bugs?.length) {
+      log.error(
+        chalk.bold(`${results.bugs.length} bug${results.bugs.length !== 1 ? "s" : ""} detected:`)
+      );
+      log.blank();
+      for (const bug of results.bugs) {
+        log.dim(`  ${chalk.red("●")} ${chalk.bold(bug.title)}`);
+        log.dim(`    ${bug.description}`);
+        log.dim(`    ${chalk.dim("at")} ${chalk.hex("#F6AD3C")(bug.location)}`);
+        log.blank();
+      }
+    }
+
+    if (ci) {
+      process.exit(failed > 0 ? 1 : 0);
+    }
+  } catch (err) {
+    spinner2.fail("Scan failed");
+    log.error(err.message);
+    log.blank();
+
+    if (err.message.includes("API error")) {
+      log.dim(
+        "The Quack API may be unavailable. Check https://status.quack.dev"
+      );
+    }
+
+    log.blank();
+    process.exit(1);
+  }
+}

package/src/lib/api.js

@@ -0,0 +1,40 @@
+import { API_BASE } from "./constants.js";
+import { getToken } from "./config.js";
+
+function headers() {
+  const token = getToken();
+  return {
+    "Content-Type": "application/json",
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  };
+}
+
+export async function apiGet(path) {
+  const res = await fetch(`${API_BASE}${path}`, { headers: headers() });
+  if (!res.ok) throw new Error(`API error: ${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+export async function apiPost(path, body) {
+  const res = await fetch(`${API_BASE}${path}`, {
+    method: "POST",
+    headers: headers(),
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`API error: ${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+export async function pollAuth(sessionId, { interval = 2000, timeout = 120000 } = {}) {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    try {
+      const data = await apiGet(`/auth/poll?session=${sessionId}`);
+      if (data.token) return data;
+    } catch {
+      // not ready yet
+    }
+    await new Promise((r) => setTimeout(r, interval));
+  }
+  throw new Error("Authentication timed out. Please try again.");
+}

package/src/lib/config.js

@@ -0,0 +1,36 @@
+import Conf from "conf";
+import { APP_NAME } from "./constants.js";
+
+const config = new Conf({
+  projectName: APP_NAME,
+  schema: {
+    token: { type: "string", default: "" },
+    userId: { type: "string", default: "" },
+    login: { type: "string", default: "" },
+    apiUrl: { type: "string", default: "https://api.quack.dev" },
+  },
+});
+
+export function getToken() {
+  return config.get("token");
+}
+
+export function setAuth({ token, userId, login }) {
+  config.set("token", token);
+  if (userId) config.set("userId", userId);
+  if (login) config.set("login", login);
+}
+
+export function clearAuth() {
+  config.clear();
+}
+
+export function isAuthenticated() {
+  return Boolean(config.get("token"));
+}
+
+export function getLogin() {
+  return config.get("login");
+}
+
+export { config };

package/src/lib/constants.js

@@ -0,0 +1,5 @@
+export const APP_NAME = "quack";
+export const API_BASE = process.env.QUACK_API_URL || "https://api.quack.dev";
+export const DASHBOARD_URL = process.env.QUACK_DASHBOARD_URL || "https://app.quack.dev";
+export const CONFIG_FILE = ".quack.json";
+export const WORKFLOW_PATH = ".github/workflows/quack.yml";

package/src/lib/logger.js

@@ -0,0 +1,14 @@
+import chalk from "chalk";
+
+const duck = chalk.hex("#F6AD3C")("🦆");
+
+export const log = {
+  info: (msg) => console.log(`${duck} ${msg}`),
+  success: (msg) => console.log(`${chalk.green("✔")} ${msg}`),
+  warn: (msg) => console.log(`${chalk.yellow("⚠")} ${msg}`),
+  error: (msg) => console.error(`${chalk.red("✖")} ${msg}`),
+  dim: (msg) => console.log(chalk.dim(`  ${msg}`)),
+  blank: () => console.log(),
+  step: (n, msg) => console.log(`${chalk.dim(`[${n}]`)} ${msg}`),
+  brand: (msg) => console.log(chalk.hex("#F6AD3C").bold(msg)),
+};