qualty 0.1.9 → 0.1.11

package/bin/local-runner.js

@@ -1,6 +1,252 @@
-import { mkdirSync, writeFileSync, mkdtempSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
+import { mkdirSync, writeFileSync, mkdtempSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import process from "node:process";
+
+function safePathSegment(value, fallback) {
+  const normalized = String(value || "").trim().replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return normalized || fallback;
+}
+
+function localAuthStatePath({ orgId, projectId, profile }) {
+  const orgSeg = safePathSegment(orgId || "default-org", "default-org");
+  const projectSeg = safePathSegment(projectId || "default-project", "default-project");
+  const profileSeg = safePathSegment(profile || "default", "default");
+  return join(homedir(), ".qualty", "local-contexts", orgSeg, projectSeg, `${profileSeg}.json`);
+}
+
+const localBindingSetupPromises = new Map();
+
+async function promptYesNo(question, defaultYes = true) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return defaultYes;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaultYes ? " [Y/n]: " : " [y/N]: ";
+    const raw = String(await rl.question(`${question}${suffix}`)).trim().toLowerCase();
+    if (!raw) return defaultYes;
+    if (raw === "y" || raw === "yes") return true;
+    if (raw === "n" || raw === "no") return false;
+    return defaultYes;
+  } finally {
+    rl.close();
+  }
+}
+
+async function runInteractiveLocalBindingSetup({
+  apiRequest,
+  apiUrl,
+  token,
+  orgId,
+  projectId,
+  profileName,
+  localProfileName,
+  startUrl,
+}) {
+  const statePath = localAuthStatePath({
+    orgId,
+    projectId,
+    profile: localProfileName,
+  });
+  mkdirSync(dirname(statePath), { recursive: true });
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const { chromium } = await import("playwright");
+    let browser = null;
+    try {
+      browser = await chromium.launch({
+        headless: false,
+        channel: "chrome",
+        args: ["--disable-blink-features=AutomationControlled"],
+      });
+      // eslint-disable-next-line no-console
+      console.log("[qualty][auth] Using local Chrome channel for login setup.");
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[qualty][auth] Chrome channel unavailable, falling back to Playwright Chromium (${err?.message || err}).`
+      );
+      browser = await chromium.launch({
+        headless: false,
+        args: ["--disable-blink-features=AutomationControlled"],
+      });
+    }
+
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const safeStartUrl = String(startUrl || "about:blank").trim() || "about:blank";
+    await page.goto(safeStartUrl, { waitUntil: "domcontentloaded", timeout: 60000 }).catch(() => {});
+    // eslint-disable-next-line no-console
+    console.log(
+      `[qualty][auth] Browser opened. Complete login for profile "${profileName}", then press Enter here.`
+    );
+    await rl.question("Press Enter to save local login state...");
+    await context.storageState({ path: statePath });
+    await context.close();
+    await browser.close();
+  } finally {
+    rl.close();
+  }
+
+  try {
+    await apiRequest({
+      apiUrl,
+      token,
+      orgId,
+      path: `/api/v1/projects/${projectId}/saved-login-profiles/local-binding`,
+      method: "POST",
+      body: {
+        profile_name: profileName,
+        local_profile_name: localProfileName,
+      },
+    });
+  } catch (syncErr) {
+    // eslint-disable-next-line no-console
+    console.warn(`[qualty][auth] Saved locally, but backend sync failed: ${syncErr?.message || syncErr}`);
+  }
+  return { profile: localProfileName, path: statePath };
+}
+
+async function maybeSetupMissingLocalBinding({
+  apiRequest,
+  apiUrl,
+  token,
+  orgId,
+  claim,
+  explicitAuthProfile,
+  noAuthState,
+}) {
+  if (noAuthState) return null;
+  if (explicitAuthProfile) return null;
+  const profile = claim?.saved_login_profile && typeof claim.saved_login_profile === "object"
+    ? claim.saved_login_profile
+    : null;
+  if (!profile || !profile.name) return null;
+  if (profile.has_local_binding) return null;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
+
+  const profileName = String(profile.name || "").trim();
+  if (!profileName) return null;
+  const key = `${String(orgId || "")}:${String(claim?.project_id || "")}:${profileName}`;
+  if (localBindingSetupPromises.has(key)) {
+    return localBindingSetupPromises.get(key);
+  }
+
+  const task = (async () => {
+    // eslint-disable-next-line no-console
+    console.log(
+      `[qualty][auth] Saved login profile "${profileName}" is attached to this test, but no local login state is configured.`
+    );
+    const shouldSetup = await promptYesNo("[qualty][auth] Create local login state now?", true);
+    if (!shouldSetup) {
+      // eslint-disable-next-line no-console
+      console.log("[qualty][auth] Continuing without local login state.");
+      return null;
+    }
+    const localProfileName = String(profile.local_profile_name || "").trim() || profileName;
+    const setupResult = await runInteractiveLocalBindingSetup({
+      apiRequest,
+      apiUrl,
+      token,
+      orgId,
+      projectId: claim.project_id,
+      profileName,
+      localProfileName,
+      startUrl: claim?.url,
+    });
+    // eslint-disable-next-line no-console
+    console.log(`[qualty][auth] Saved local login state for "${profileName}".`);
+    return setupResult;
+  })();
+
+  localBindingSetupPromises.set(key, task);
+  try {
+    return await task;
+  } finally {
+    localBindingSetupPromises.delete(key);
+  }
+}
+
+async function preflightMissingLocalBindings({
+  apiRequest,
+  apiUrl,
+  token,
+  orgId,
+  projectId,
+  savedJobs,
+  explicitAuthProfile,
+  noAuthState,
+}) {
+  if (noAuthState) return;
+  if (explicitAuthProfile) return;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+  const missingByProfile = new Map();
+  for (const job of savedJobs || []) {
+    const useSaved = Boolean(job?.use_saved_login);
+    const profileName = String(job?.saved_login_profile?.name || "").trim();
+    if (!useSaved || !profileName) continue;
+    const statePath = localAuthStatePath({
+      orgId,
+      projectId: String(job?.project_id || projectId || "").trim(),
+      profile: profileName,
+    });
+    if (existsSync(statePath)) continue;
+    const entry = missingByProfile.get(profileName) || {
+      localProfileName: profileName,
+      projectId: String(job?.project_id || projectId || "").trim(),
+      startUrl: String(job?.url || "").trim(),
+      tests: [],
+    };
+    entry.tests.push({
+      id: String(job?.id || "").trim(),
+      name: String(job?.name || job?.id || "Unnamed test").trim(),
+    });
+    if (!entry.startUrl) entry.startUrl = String(job?.url || "").trim();
+    missingByProfile.set(profileName, entry);
+  }
+  if (missingByProfile.size === 0) return;
+
+  // eslint-disable-next-line no-console
+  console.log("[qualty][auth] Missing local login state for attached dashboard profiles:");
+  for (const [profileName, entry] of missingByProfile.entries()) {
+    // eslint-disable-next-line no-console
+    console.log(`  - Profile "${profileName}" is required by:`);
+    for (const test of entry.tests) {
+      // eslint-disable-next-line no-console
+      console.log(`      - ${test.name} (${test.id})`);
+    }
+  }
+
+  for (const [profileName, entry] of missingByProfile.entries()) {
+    const shouldSetup = await promptYesNo(
+      `[qualty][auth] Set up local login now for profile "${profileName}"?`,
+      true
+    );
+    if (!shouldSetup) {
+      throw new Error(
+        `Cancelled: local login state is required for attached profile "${profileName}".`
+      );
+    }
+    await runInteractiveLocalBindingSetup({
+      apiRequest,
+      apiUrl,
+      token,
+      orgId,
+      projectId: entry.projectId,
+      profileName,
+      localProfileName: entry.localProfileName,
+      startUrl: entry.startUrl,
+    });
+    // eslint-disable-next-line no-console
+    console.log(`[qualty][auth] Saved local login state for "${profileName}".`);
+  }
+
+  const confirmed = await promptYesNo("[qualty] Login setup complete. Start all local runs now?", true);
+  if (!confirmed) {
+    throw new Error("Run cancelled by user before starting tests.");
+  }
+}
 
 async function downloadProjectAttachments({ apiUrl, token, orgId, projectId, specs }) {
   const labelToPath = {};
@@ -754,6 +1000,9 @@ export async function runLocalExecution({
   executionId,
   device,
   headless,
+  authProfile,
+  noAuthState,
+  storageStatePath,
 }) {
   const { chromium } = await import("playwright");
 
@@ -770,6 +1019,36 @@ export async function runLocalExecution({
   const viewport = claim.viewport || { width: 1440, height: 900 };
   const steps = Array.isArray(claim.steps) ? claim.steps : [];
   const totalSteps = claim.total_steps || steps.length;
+  const claimSavedLogin = claim.saved_login_profile && typeof claim.saved_login_profile === "object"
+    ? claim.saved_login_profile
+    : null;
+  const setupFromClaim = await maybeSetupMissingLocalBinding({
+    apiRequest,
+    apiUrl,
+    token,
+    orgId,
+    claim,
+    explicitAuthProfile: String(authProfile || "").trim(),
+    noAuthState: Boolean(noAuthState),
+  });
+  const claimProfile = String(claimSavedLogin?.local_profile_name || "").trim();
+  const effectiveProfile = String(authProfile || "").trim() || setupFromClaim?.profile || claimProfile;
+  const resolvedStoragePath =
+    !noAuthState && effectiveProfile
+      ? localAuthStatePath({
+          orgId,
+          projectId: claim.project_id,
+          profile: effectiveProfile,
+        })
+      : null;
+  const finalStoragePath =
+    !noAuthState && setupFromClaim?.path && existsSync(setupFromClaim.path)
+      ? setupFromClaim.path
+      : !noAuthState && storageStatePath && existsSync(storageStatePath)
+      ? storageStatePath
+      : !noAuthState && resolvedStoragePath && existsSync(resolvedStoragePath)
+        ? resolvedStoragePath
+        : null;
 
   const browserServer = await chromium.launchServer({
     headless: headless !== false,
@@ -777,9 +1056,15 @@ export async function runLocalExecution({
   });
   const cdpEndpoint = browserServer.wsEndpoint();
   const browser = await chromium.connect(cdpEndpoint);
-  const context = await browser.newContext({
+  const contextOptions = {
     viewport: { width: viewport.width || 1440, height: viewport.height || 900 },
-  });
+  };
+  if (finalStoragePath) {
+    contextOptions.storageState = finalStoragePath;
+    const logProfile = effectiveProfile || "default";
+    console.log(`[qualty][auth] using saved context "${logProfile}": ${finalStoragePath}`);
+  }
+  const context = await browser.newContext(contextOptions);
   const page = await context.newPage();
   const networkCollector = attachNetworkCollector(page);
   const labelToPath = await downloadProjectAttachments({
@@ -985,6 +1270,9 @@ export async function runLocalCi({
   device,
   headless,
   localConcurrency = 4,
+  authProfile,
+  noAuthState,
+  storageStatePath,
 }) {
   const savedJobs = await resolveSavedJobs({ apiUrl, token, orgId, projectId, suiteId, explicitIds });
   if (!Array.isArray(savedJobs) || savedJobs.length === 0) {
@@ -1009,6 +1297,17 @@ export async function runLocalCi({
   const started = runs.filter((r) => r.execution_job_id);
   if (started.length === 0) throw new Error("Failed to start any local runs.");
 
+  await preflightMissingLocalBindings({
+    apiRequest,
+    apiUrl,
+    token,
+    orgId,
+    projectId,
+    savedJobs,
+    explicitAuthProfile: String(authProfile || "").trim(),
+    noAuthState: Boolean(noAuthState),
+  });
+
   const concurrency = Math.max(1, Number(localConcurrency) || 4);
   const workerCount = Math.min(concurrency, started.length);
 
@@ -1040,6 +1339,9 @@ export async function runLocalCi({
           executionId: id,
           device,
           headless,
+          authProfile,
+          noAuthState,
+          storageStatePath,
         });
         if (result.success) {
           passed += 1;

package/bin/qualty.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import process from "node:process";
 import { runLocalCi } from "./local-runner.js";
 
 /** CLI backend URL is fixed by Qualty distribution. */
-const DEFAULT_QUALTY_API_URL = "https://qualty-api-development.up.railway.app";
+// const DEFAULT_QUALTY_API_URL = "https://qualty-api-development.up.railway.app";
+const DEFAULT_QUALTY_API_URL = "http://localhost:8000";
+
 const QUALTY_CONFIG_DIR = join(homedir(), ".config", "qualty");
 const QUALTY_CONFIG_PATH = join(QUALTY_CONFIG_DIR, "config.json");
 const QUALTY_SHARED_CREDS_DIR = join(homedir(), ".qualty");
@@ -133,10 +135,11 @@ function usage() {
     [
       "Usage:",
       "  qualty setup [--token <bearer-token>] [--org <org-id>]",
+      "  qualty auth setup [--project <project-id>] [--profile <profile-name>] [--headed]",
       "  qualty connect --project <project-id> [--port 3000] [--token <bearer-token>] [--org <org-id>]",
       "  qualty run --project <project-id> [--suite-id <suite-id>] [--ids <id1,id2>] [--local] [--token <bearer-token>] [--org <org-id>]",
       "             [--poll-interval 5] [--timeout 30] [--fail-on-failure true] [--no-view-logs]",
-      "             [--local] [--device 1440x900] [--headed] [--local-concurrency 4]",
+      "             [--local] [--device 1440x900] [--headed] [--local-concurrency 4] [--auth-profile <profile>] [--no-auth-state] [--prompt-auth-profile]",
       "",
       "  After each run, logs include step results, explanation, and final evaluator output (dashboard \"View logs\" data).",
       "  Pass --no-view-logs for a short log only (e.g. very large evaluator text).",
@@ -169,6 +172,29 @@ async function apiRequest({ apiUrl, token, orgId, path, method = "GET", body })
   return data;
 }
 
+async function registerLocalLoginProfileBinding({
+  apiUrl,
+  token,
+  orgId,
+  projectId,
+  profileName,
+  localProfileName,
+}) {
+  if (!projectId || !profileName) return null;
+  return apiRequest({
+    apiUrl,
+    token,
+    orgId,
+    path: `/api/v1/projects/${projectId}/saved-login-profiles/local-binding`,
+    method: "POST",
+    body: {
+      profile_name: profileName,
+      local_profile_name: localProfileName || profileName,
+      machine_id: hostname(),
+    },
+  });
+}
+
 function startCloudflared(token, port) {
   const baseArgs = [
     "tunnel",
@@ -445,6 +471,38 @@ function resolveLocalConcurrency(args) {
   return n;
 }
 
+function safePathSegment(value, fallback = "default") {
+  const out = String(value || "")
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return out || fallback;
+}
+
+function localAuthStatePath({ orgId, projectId, profile }) {
+  const orgSeg = safePathSegment(orgId || "default-org", "default-org");
+  const projectSeg = safePathSegment(projectId || "default-project", "default-project");
+  const profileSeg = safePathSegment(profile || "default", "default");
+  return join(QUALTY_SHARED_CREDS_DIR, "local-contexts", orgSeg, projectSeg, `${profileSeg}.json`);
+}
+
+function listLocalAuthProfiles({ orgId, projectId }) {
+  const orgSeg = safePathSegment(orgId || "default-org", "default-org");
+  const projectSeg = safePathSegment(projectId || "default-project", "default-project");
+  const dir = join(QUALTY_SHARED_CREDS_DIR, "local-contexts", orgSeg, projectSeg);
+  if (!existsSync(dir)) return [];
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith(".json"))
+      .map((e) => e.name.replace(/\.json$/i, ""))
+      .filter(Boolean)
+      .sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1087,6 +1145,203 @@ async function maybePromptProjectIdForLocalRun({ args, apiUrl, token, orgId }) {
   }
 }
 
+function resolveLocalAuthStateForRun({ args, orgId, projectId }) {
+  if (parseBoolean(args["no-auth-state"], false)) return null;
+  const requestedProfile = String(args["auth-profile"] || "").trim();
+  const profile = requestedProfile;
+  if (!profile) return null;
+  const path = localAuthStatePath({ orgId, projectId, profile });
+  if (!existsSync(path)) return null;
+  return { profile, path };
+}
+
+async function maybePromptAuthProfileForLocalRun({ args, orgId, projectId }) {
+  const requestedProfile = String(args["auth-profile"] || "").trim();
+  if (requestedProfile) return { authProfile: requestedProfile, noAuthState: false };
+  if (parseBoolean(args["no-auth-state"], false)) return { authProfile: "", noAuthState: true };
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return { authProfile: "", noAuthState: false };
+  if (!projectId) return { authProfile: "", noAuthState: false };
+
+  const profiles = listLocalAuthProfiles({ orgId, projectId });
+  if (profiles.length === 0) return { authProfile: "", noAuthState: false };
+
+  const projectCfg = readProjectConfig();
+  const defaultProfile = String(projectCfg.local_auth_profile || "").trim();
+  const defaultIndex = profiles.findIndex((p) => p === defaultProfile);
+
+  // eslint-disable-next-line no-console
+  console.log("[qualty][auth] Choose saved login state:");
+  // eslint-disable-next-line no-console
+  console.log("  0) Run without saved login state");
+  for (let i = 0; i < profiles.length; i += 1) {
+    const isDefault = defaultIndex === i ? " (default)" : "";
+    // eslint-disable-next-line no-console
+    console.log(`  ${i + 1}) ${profiles[i]}${isDefault}`);
+  }
+
+  const defaultChoice = defaultIndex >= 0 ? defaultIndex + 1 : 0;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    while (true) {
+      const raw = String(
+        await rl.question(`Select login state [0-${profiles.length}] (default ${defaultChoice}): `)
+      ).trim();
+      const picked = raw ? Number(raw) : defaultChoice;
+      if (!Number.isInteger(picked) || picked < 0 || picked > profiles.length) {
+        // eslint-disable-next-line no-console
+        console.log(`[qualty] Please enter a number from 0 to ${profiles.length}.`);
+        continue;
+      }
+      if (picked === 0) {
+        // eslint-disable-next-line no-console
+        console.log("[qualty][auth] Running without saved login state.");
+        return { authProfile: "", noAuthState: true };
+      }
+      const profile = profiles[picked - 1];
+      // eslint-disable-next-line no-console
+      console.log(`[qualty][auth] Selected profile "${profile}"`);
+      return { authProfile: profile, noAuthState: false };
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+async function runAuthSetup(args) {
+  const config = readQualtyConfig();
+  const apiUrl = resolveApiUrl(args, config);
+  const token = resolveToken(args, config);
+  const orgId = resolveOrgId(args, config);
+  if (!token) {
+    throw new Error("Missing auth token. Run `qualty setup` first.");
+  }
+  if (!orgId) {
+    throw new Error("Missing org. Run `qualty setup` first.");
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("Interactive auth setup requires a TTY terminal.");
+  }
+
+  const projectsPayload = await apiRequest({
+    apiUrl,
+    token,
+    orgId,
+    path: "/api/v1/projects",
+  });
+  const projects = (Array.isArray(projectsPayload) ? projectsPayload : [])
+    .map((p) => ({
+      id: String(p?.id || "").trim(),
+      name: String(p?.name || "").trim() || "Unnamed project",
+      url: String(p?.url || "").trim(),
+    }))
+    .filter((p) => p.id);
+  if (projects.length === 0) {
+    throw new Error("No projects found. Create a project first.");
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  let project = null;
+  try {
+    const requestedProjectId = String(args.project || "").trim();
+    if (requestedProjectId) {
+      project = projects.find((p) => p.id === requestedProjectId) || null;
+      if (!project) {
+        throw new Error(`Project ${requestedProjectId} not found.`);
+      }
+    } else {
+      // eslint-disable-next-line no-console
+      console.log("[qualty] Choose project for saved local auth:");
+      for (let i = 0; i < projects.length; i += 1) {
+        // eslint-disable-next-line no-console
+        console.log(`  ${i + 1}) ${projects[i].name}`);
+      }
+      while (!project) {
+        const raw = String(await rl.question(`Select project [1-${projects.length}] (default 1): `)).trim();
+        const picked = raw ? Number(raw) : 1;
+        if (Number.isInteger(picked) && picked >= 1 && picked <= projects.length) {
+          project = projects[picked - 1];
+        } else {
+          // eslint-disable-next-line no-console
+          console.log(`[qualty] Please enter a number from 1 to ${projects.length}.`);
+        }
+      }
+    }
+
+    let profile = String(args.profile || "").trim();
+    if (!profile) {
+      const current = String(readProjectConfig().local_auth_profile || "default").trim() || "default";
+      profile = String(await rl.question(`Profile name [${current}]: `)).trim() || current;
+    }
+    const statePath = localAuthStatePath({
+      orgId,
+      projectId: project.id,
+      profile,
+    });
+    mkdirSync(join(statePath, ".."), { recursive: true });
+
+    const { chromium } = await import("playwright");
+    const headed = parseBoolean(args.headed, true);
+    let browser = null;
+    try {
+      browser = await chromium.launch({
+        headless: !headed,
+        channel: "chrome",
+        args: ["--disable-blink-features=AutomationControlled"],
+      });
+      // eslint-disable-next-line no-console
+      console.log("[qualty][auth] Using local Chrome channel for login setup.");
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.log(`[qualty][auth] Chrome channel unavailable, falling back to Playwright Chromium (${err?.message || err}).`);
+      browser = await chromium.launch({
+        headless: !headed,
+        args: ["--disable-blink-features=AutomationControlled"],
+      });
+    }
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const startUrl = project.url || "about:blank";
+    await page.goto(startUrl, { waitUntil: "domcontentloaded", timeout: 60000 }).catch(() => {});
+    // eslint-disable-next-line no-console
+    console.log(`[qualty][auth] Browser opened for project "${project.name}".`);
+    // eslint-disable-next-line no-console
+    console.log("[qualty][auth] Complete login in the browser, then press Enter here to save context.");
+    await rl.question("Press Enter to save local auth context...");
+    await context.storageState({ path: statePath });
+    await context.close();
+    await browser.close();
+
+    writeProjectConfig({
+      local_auth_project_id: project.id,
+      local_auth_profile: profile,
+      default_org_id: orgId,
+    });
+    try {
+      const synced = await registerLocalLoginProfileBinding({
+        apiUrl,
+        token,
+        orgId,
+        projectId: project.id,
+        profileName: profile,
+        localProfileName: profile,
+      });
+      if (synced?.name) {
+        // eslint-disable-next-line no-console
+        console.log(`[qualty][auth] Synced profile reference "${synced.name}" to dashboard.`);
+      }
+    } catch (syncErr) {
+      // eslint-disable-next-line no-console
+      console.warn(`[qualty][auth] Failed to sync profile reference to backend: ${syncErr?.message || syncErr}`);
+    }
+    // eslint-disable-next-line no-console
+    console.log(`[qualty][auth] Saved local context profile "${profile}" for project "${project.name}".`);
+    // eslint-disable-next-line no-console
+    console.log(`[qualty][auth] Path: ${statePath}`);
+  } finally {
+    rl.close();
+  }
+}
+
 async function main() {
   const args = parseArgs(process.argv);
   const command = args._[0];
@@ -1102,6 +1357,14 @@ async function main() {
     await runSetup(args);
     return;
   }
+  if (command === "auth") {
+    const sub = args._[1];
+    if (sub === "setup") {
+      await runAuthSetup(args);
+      return;
+    }
+    throw new Error("Unknown auth subcommand. Use: qualty auth setup");
+  }
   if (command === "run") {
     const config = readQualtyConfig();
     if (parseBoolean(args.local, false)) {
@@ -1122,6 +1385,27 @@ async function main() {
           token,
           orgId,
         })) || args["suite-id"];
+      const shouldPromptAuthProfile = parseBoolean(args["prompt-auth-profile"], false);
+      const authChoice = shouldPromptAuthProfile
+        ? await maybePromptAuthProfileForLocalRun({
+            args,
+            orgId,
+            projectId,
+          })
+        : {
+            authProfile: String(args["auth-profile"] || "").trim(),
+            noAuthState: parseBoolean(args["no-auth-state"], false),
+          };
+      const localAuthArgs = {
+        ...args,
+        ...(authChoice.authProfile ? { "auth-profile": authChoice.authProfile } : {}),
+        ...(authChoice.noAuthState ? { "no-auth-state": true } : {}),
+      };
+      const localAuth = resolveLocalAuthStateForRun({ args: localAuthArgs, orgId, projectId });
+      if (localAuth?.path) {
+        // eslint-disable-next-line no-console
+        console.log(`[qualty][auth] Reusing profile "${localAuth.profile}"`);
+      }
       await runLocalCi({
         apiUrl,
         token,
@@ -1138,6 +1422,9 @@ async function main() {
         device: args.device || "1440x900",
         headless: !parseBoolean(args.headed, false),
         localConcurrency: resolveLocalConcurrency(args),
+        authProfile: localAuth?.profile || authChoice.authProfile || "",
+        noAuthState: Boolean(authChoice.noAuthState || parseBoolean(args["no-auth-state"], false)),
+        storageStatePath: localAuth?.path,
       });
       return;
     }
@@ -1148,7 +1435,13 @@ async function main() {
     await runResolve(args);
     return;
   }
-  if (command !== "setup" && command !== "connect" && command !== "run" && command !== "resolve") {
+  if (
+    command !== "setup" &&
+    command !== "auth" &&
+    command !== "connect" &&
+    command !== "run" &&
+    command !== "resolve"
+  ) {
     throw new Error(`Unknown command: ${command}`);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualty",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Qualty CLI for localhost and CI test runs",
   "bin": {
     "qualty": "bin/qualty.js"