@qawolf/cli 1.3.2 → 1.4.0

package/dist/cli.js

@@ -173598,7 +173598,7 @@ function registerAuthCommand(program2, signals) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.3.2",
+  version: "1.4.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -173658,7 +173658,7 @@ var package_default = {
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
     "@playwright/test": "1.60.0",
-    "@qawolf/api-contracts": "0.2.0",
+    "@qawolf/api-contracts": "0.11.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -175676,9 +175676,125 @@ var import_picomatch2 = __toESM(require_picomatch2(), 1);
 
 // node_modules/@qawolf/api-contracts/dist/v1/ids.js
 var defaultIdSchemas = {
+  automation: exports_external.string().min(1).describe("The id of the automation."),
   environment: exports_external.string().min(1).describe("The id of the environment."),
   flow: exports_external.string().min(1).describe("The id of the flow."),
-  run: exports_external.string().min(1).describe("The id of the run.")
+  issue: exports_external.string().min(1).describe("The id of the issue."),
+  run: exports_external.string().min(1).describe("The id of the run."),
+  workspace: exports_external.string().min(1).describe("The id of the workspace.")
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/resource.js
+function resource(fields, { urlFieldDescription = "Absolute URL." } = {}) {
+  return exports_external.object({
+    ...fields,
+    url: exports_external.url().describe(urlFieldDescription)
+  });
+}
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/flowSelection.js
+var makeFlowSelectionSchema = (ids) => exports_external.object({
+  flowIds: exports_external.array(ids.flow).default([]),
+  tagNames: exports_external.array(exports_external.string().min(1)).default([])
+}).refine((selection) => selection.flowIds.length + selection.tagNames.length > 0, {
+  message: "At least one flow or tag is required."
+});
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/index.js
+var makeCreateRunContract = (ids) => {
+  const input = exports_external.object({
+    environmentId: ids.environment,
+    environmentVariables: exports_external.record(exports_external.string(), exports_external.string()).optional(),
+    ignoreRules: exports_external.boolean().default(false),
+    pullRequestNumber: exports_external.number().int().positive().describe("The number of the pull request to associate with the run.").optional(),
+    repository: exports_external.string().min(1).describe('The owner/name of the repository, e.g. "acme/web".').optional()
+  }).and(makeFlowSelectionSchema(ids));
+  const output = resource({ runId: ids.run }, { urlFieldDescription: "Absolute URL of the run page." });
+  return {
+    description: "Create a run for the selected flows and/or tags in an environment.",
+    input,
+    kind: "write",
+    name: "run.create",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/automate/index.js
+var makeAutomateContract = (ids) => {
+  const input = exports_external.object({
+    environmentId: ids.environment,
+    flowIds: exports_external.array(ids.flow).min(1).max(300).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("Draft flows the automation builds."),
+    patch: exports_external.string().min(1).max(1e6).optional().describe("Unified diff applied to the automation's working branch before it runs.")
+  });
+  const output = resource({ automationId: ids.automation }, { urlFieldDescription: "Absolute URL of the automation review page." });
+  return {
+    description: "Request an automation that builds the selected draft flows in an environment.",
+    input,
+    kind: "write",
+    name: "automate",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/environment/index.js
+var makeEnvironmentResource = (environmentId) => resource({
+  environmentId,
+  flowCodeBranch: exports_external.discriminatedUnion("syncStatus", [
+    exports_external.object({
+      lastSyncedCommitHash: exports_external.string().describe("Hash of the latest reconciled commit."),
+      name: exports_external.string().describe("The name of the environment's flow code branch."),
+      syncStatus: exports_external.literal("reconciled").describe("The branch has reconciled at least one commit.")
+    }),
+    exports_external.object({
+      name: exports_external.string().describe("The name of the environment's flow code branch."),
+      syncStatus: exports_external.literal("not-reconciled").describe("The branch has not reconciled any commit yet.")
+    })
+  ]).optional().describe("The environment's flow code branch and its git reconciliation state, if it has one."),
+  kind: exports_external.enum(["static", "preview"]).describe("Whether the environment is static or a preview."),
+  name: exports_external.string(),
+  status: exports_external.enum(["blocked", "needs-investigation", "ready", "running"]).describe("Standing health across the environment's runs: blocked (open blocking bugs), needs-investigation (failures awaiting triage), running (flows executing), ready (none of the above — the greenlit state)."),
+  terminatedAt: exports_external.iso.datetime().optional().describe("When the environment was terminated, if it has been.")
+}, { urlFieldDescription: "Absolute URL of the environment page." });
+var makeGetEnvironmentContract = (ids) => {
+  const input = exports_external.object({
+    environmentId: ids.environment
+  });
+  const output = makeEnvironmentResource(ids.environment);
+  return {
+    description: "Read a single environment's name, kind, health status, and termination state.",
+    input,
+    kind: "read",
+    name: "environment.get",
+    output
+  };
+};
+var makeListEnvironmentVariableNamesContract = (ids) => {
+  const input = exports_external.object({
+    environmentId: ids.environment
+  });
+  const output = exports_external.object({
+    variableNames: exports_external.array(exports_external.string()).describe("Names of the environment's variables, sorted alphabetically. Values are never returned.")
+  });
+  return {
+    description: "List the names of an environment's variables, sorted. Names only — values never leave the server.",
+    input,
+    kind: "read",
+    name: "environment.listVariableNames",
+    output
+  };
+};
+var makeCreateEnvironmentContract = (ids) => {
+  const input = exports_external.object({
+    name: exports_external.string().min(1).max(255).regex(/\S/, "Environment name cannot be blank.").describe("Display name of the new environment.")
+  });
+  const output = makeEnvironmentResource(ids.environment);
+  return {
+    description: "Create an environment on the caller's team and return it in the environment.get shape.",
+    input,
+    kind: "write",
+    name: "environment.create",
+    output
+  };
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/flow/index.js
@@ -175689,12 +175805,14 @@ var makeListFlowsContract = (ids) => {
   });
   const executionTarget = exports_external.union([exports_external.string().min(1), exports_external.record(exports_external.string(), exports_external.unknown())]).describe("The target the flow executes against, as a preset or object.");
   const output = exports_external.object({
-    flows: exports_external.array(exports_external.object({
+    flows: exports_external.array(resource({
       executionTarget,
       flowId: ids.flow,
       name: exports_external.string(),
       path: exports_external.string().describe("The flow file path, relative to the repo."),
       tags: exports_external.array(exports_external.string())
+    }, {
+      urlFieldDescription: "Absolute URL of the flow page in its environment."
     }))
   });
   return {
@@ -175706,33 +175824,229 @@ var makeListFlowsContract = (ids) => {
   };
 };
 
-// node_modules/@qawolf/api-contracts/dist/v1/run/index.js
-var makeCreateRunContract = (ids) => {
-  const input = exports_external.object({
+// node_modules/@qawolf/api-contracts/dist/v1/pagination.js
+var makePaginationInputFields = (limits) => ({
+  cursor: exports_external.string().min(1).optional().describe("Opaque cursor copied from the previous response's nextCursor. Omit to fetch the first page."),
+  limit: exports_external.number().int().min(1).max(limits.maxLimit).default(limits.defaultLimit).describe(`Maximum rows per page. Defaults to ${limits.defaultLimit}, capped at ${limits.maxLimit}.`)
+});
+var nextCursorSchema = exports_external.string().min(1).optional().describe("Repeat the request with this value as cursor to fetch the next page. Absent when there are no further results.");
+
+// node_modules/@qawolf/api-contracts/dist/v1/issue/index.js
+var issuePrioritySchema = exports_external.enum([
+  "unprioritized",
+  "low",
+  "medium",
+  "high",
+  "urgent"
+]);
+var issueStatusSchema = exports_external.enum([
+  "pending",
+  "inProgress",
+  "paused",
+  "resolved",
+  "canceled",
+  "archived"
+]);
+var publicIssueTypeSchema = exports_external.enum(["bug", "coverageRequest", "maintenance"]);
+var openIssueStatuses = ["pending", "inProgress", "paused"];
+var makeIssueResourceSchema = (ids) => resource({
+  createdAt: exports_external.coerce.date().describe("When the issue was created."),
+  description: exports_external.string().describe("The issue description in Markdown."),
+  issueId: ids.issue,
+  name: exports_external.string(),
+  number: exports_external.number().int(),
+  priority: issuePrioritySchema,
+  reproductions: exports_external.array(exports_external.object({
     environmentId: ids.environment,
-    environmentVariables: exports_external.record(exports_external.string(), exports_external.string()).optional(),
-    flowIds: exports_external.array(ids.flow).min(1),
-    ignoreRules: exports_external.boolean().default(false)
+    firstReproducedInRunId: ids.run,
+    flowId: ids.flow,
+    isActive: exports_external.boolean(),
+    lastReproducedInRunId: ids.run
+  })).describe("The environments, flows, and runs where the issue was reproduced."),
+  status: issueStatusSchema,
+  type: publicIssueTypeSchema
+}, { urlFieldDescription: "Absolute URL of the issue page." });
+var makeFindIssuesContract = (ids) => {
+  const input = exports_external.object({
+    ...makePaginationInputFields({ defaultLimit: 20, maxLimit: 100 }),
+    statuses: exports_external.array(issueStatusSchema).min(1).default([...openIssueStatuses]).describe("Issue statuses to include. Defaults to pending, in-progress, and paused issues."),
+    type: publicIssueTypeSchema.describe("The issue type to include: bug report, maintenance report, or coverage request.")
+  });
+  const output = exports_external.object({
+    issues: exports_external.array(makeIssueResourceSchema(ids)).describe("The team's bug reports, maintenance reports, or coverage requests, newest first."),
+    nextCursor: nextCursorSchema
   });
-  const output = exports_external.object({ runId: ids.run });
   return {
-    description: "Create a run for selected flows in an environment.",
+    description: "List the team's bug reports, maintenance reports, or coverage requests, newest first.",
+    input,
+    kind: "read",
+    name: "issue.find",
+    output
+  };
+};
+var makeGetIssueContract = (ids) => {
+  const input = exports_external.object({
+    issueId: ids.issue
+  });
+  const output = exports_external.object({
+    issue: makeIssueResourceSchema(ids)
+  });
+  return {
+    description: "Get an issue by id.",
+    input,
+    kind: "read",
+    name: "issue.get",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/issue/create.js
+var makeCreateIssueContract = (ids) => {
+  const commonFields = {
+    description: exports_external.string().optional().describe("The issue description as plain text; each line becomes a paragraph. Markdown is not parsed."),
+    name: exports_external.string().trim().min(1).max(255),
+    priority: issuePrioritySchema.optional().describe('Defaults to "unprioritized".')
+  };
+  const input = exports_external.discriminatedUnion("type", [
+    exports_external.object({
+      ...commonFields,
+      type: exports_external.literal("bug")
+    }),
+    exports_external.object({
+      ...commonFields,
+      estimatedDueDate: exports_external.iso.date().optional().describe("The calendar date the coverage is estimated to be complete, as YYYY-MM-DD."),
+      type: exports_external.literal("coverageRequest")
+    })
+  ]);
+  const output = exports_external.object({
+    issue: makeIssueResourceSchema(ids)
+  });
+  return {
+    description: "Create a bug or coverage request issue for the caller's team. " + "Maintenance issues cannot be created through the public API.",
     input,
     kind: "write",
-    name: "run.create",
+    name: "issue.create",
     output
   };
 };
 
-// node_modules/@qawolf/api-contracts/dist/v1/index.js
-var makeContractsV1 = (ids) => ({
-  flow: {
-    list: makeListFlowsContract(ids)
-  },
-  run: {
-    create: makeCreateRunContract(ids)
-  }
+// node_modules/@qawolf/api-contracts/dist/v1/run/summary.js
+var makeRunSummaryFields = (ids) => ({
+  completedAt: exports_external.iso.datetime().optional().describe("When the run finished executing. Absent while queued or running, and also absent for a terminal run that never completed execution (e.g. every flow was canceled or skipped)."),
+  createdAt: exports_external.iso.datetime(),
+  git: exports_external.object({
+    branch: exports_external.string().optional(),
+    commitMessage: exports_external.string().optional(),
+    commitSha: exports_external.string().optional(),
+    commitUrl: exports_external.string().optional().describe("Link to the commit on the code host.")
+  }).describe("The branch and commit under test. The fields are present when a deploy notification started the run, and absent for runs started another way, for example manually or with run.create."),
+  runId: ids.run,
+  status: exports_external.enum(["queued", "running", "passed", "failed", "canceled"]).describe("Whole-run status. Terminal statuses are passed, failed, and canceled; poll until one is reached.")
+});
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/find.js
+var makeFindRunsContract = (ids) => {
+  const input = exports_external.object({
+    createdAfter: exports_external.iso.datetime({ offset: true }).optional().describe("Only include runs created after this instant, e.g. the runs since a deploy."),
+    ...makePaginationInputFields({ defaultLimit: 20, maxLimit: 100 }),
+    environmentId: ids.environment
+  });
+  const output = exports_external.object({
+    nextCursor: nextCursorSchema,
+    runs: exports_external.array(resource(makeRunSummaryFields(ids), {
+      urlFieldDescription: "Absolute URL of the run page."
+    })).describe("The environment's runs, newest first. Per-flow results are available via run.get.")
+  });
+  return {
+    description: "List an environment's recent runs, newest first.",
+    input,
+    kind: "read",
+    name: "run.find",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/get.js
+var makeGetRunContract = (ids) => {
+  const input = exports_external.object({
+    runId: ids.run
+  });
+  const failedFlow = exports_external.object({
+    failure: exports_external.object({
+      error: exports_external.string()
+    }),
+    flowId: ids.flow,
+    name: exports_external.string(),
+    status: exports_external.literal("failed")
+  });
+  const nonFailedFlow = exports_external.object({
+    flowId: ids.flow,
+    name: exports_external.string(),
+    status: exports_external.enum(["queued", "running", "passed", "canceled"])
+  });
+  const flows = exports_external.array(exports_external.discriminatedUnion("status", [failedFlow, nonFailedFlow])).describe("The run's flows, ordered alphabetically by name.");
+  const output = resource({
+    ...makeRunSummaryFields(ids),
+    flows
+  }, { urlFieldDescription: "Absolute URL of the run page." });
+  return {
+    description: "Get a run's status, per-flow results, and links.",
+    input,
+    kind: "read",
+    name: "run.get",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/tag/index.js
+var makeTagResourceSchema = () => resource({
+  color: exports_external.string().regex(/^#[0-9a-fA-F]{6}$/).describe("The tag's display color as a hex code, assigned by QA Wolf."),
+  name: exports_external.string()
+}, {
+  urlFieldDescription: "Absolute URL of the team's tag settings page."
 });
+var makeCreateTagContract = () => {
+  const input = exports_external.object({
+    name: exports_external.string().trim().min(1).max(255).refine((name) => !name.includes(","), "Tag names cannot include commas.")
+  });
+  const output = makeTagResourceSchema();
+  return {
+    description: "Create a tag on the caller's team. Tags select flows in run.create.",
+    input,
+    kind: "write",
+    name: "tag.create",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/index.js
+var makeContractsV1 = (ids) => {
+  const resolvedIds = { ...defaultIdSchemas, ...ids };
+  return {
+    automate: makeAutomateContract(resolvedIds),
+    environment: {
+      create: makeCreateEnvironmentContract(resolvedIds),
+      get: makeGetEnvironmentContract(resolvedIds),
+      listVariableNames: makeListEnvironmentVariableNamesContract(resolvedIds)
+    },
+    flow: {
+      list: makeListFlowsContract(resolvedIds)
+    },
+    issue: {
+      create: makeCreateIssueContract(resolvedIds),
+      find: makeFindIssuesContract(resolvedIds),
+      get: makeGetIssueContract(resolvedIds)
+    },
+    run: {
+      create: makeCreateRunContract(resolvedIds),
+      find: makeFindRunsContract(resolvedIds),
+      get: makeGetRunContract(resolvedIds)
+    },
+    tag: {
+      create: makeCreateTagContract()
+    }
+  };
+};
 var publicContractsV1 = makeContractsV1(defaultIdSchemas);
 
 // src/domains/flows/listRemote.ts
@@ -179740,8 +180054,7 @@ async function dispatchFlow({
     run = { ...run, manifest: stamp };
   const durationMs = deps.now() - flowStart;
   const outcome = run.passed ? "pass" : "fail";
-  const attempts = run.attempts;
-  const attempt = pluralize(attempts, "attempt");
+  const attempt = pluralize(run.attempts, "attempt");
   deps.logger?.info(`${outcome}: ${flow.name} (${durationMs}ms, ${attempt})`);
   return { run, durationMs };
 }
@@ -180923,7 +181236,7 @@ async function installBrowserList(ctx, browsers, deps) {
   await ctx.ui.withProgress(browsers.map((browser) => ({
     message: installMessages.installingBrowser(browser),
     task: async () => {
-      const args = buildArgs(browser, deps.platform);
+      const args = buildArgs(browser, deps.platform, deps.browserDeps);
       const result = await deps.spawn(deps.playwrightCliPath, args);
       if (result.exitCode !== 0) {
         throw new Error(formatError2(browser, result));
@@ -180943,6 +181256,7 @@ async function installBrowsers(ctx, pattern, deps) {
   await installBrowserList(ctx, browsers, {
     spawn: deps.spawn,
     platform: deps.platform,
+    browserDeps: deps.browserDeps,
     playwrightCliPath
   });
 }
@@ -180957,8 +181271,8 @@ async function collectBrowsers(files, peekFlowMeta) {
   }
   return [...seen].sort();
 }
-function buildArgs(browser, platform) {
-  return platform === "linux" ? ["install", "--with-deps", browser] : ["install", browser];
+function buildArgs(browser, platform, browserDeps) {
+  return platform === "linux" && browserDeps ? ["install", "--with-deps", browser] : ["install", browser];
 }
 function formatError2(browser, result) {
   if (result.exitCode < 0) {
@@ -182180,6 +182494,7 @@ function buildFlowsRunDeps(args) {
     installBrowsers: (innerCtx, browsers) => installBrowserList(innerCtx, browsers, {
       spawn: defaultSpawn,
       platform: process.platform,
+      browserDeps: flags.browserDeps,
       playwrightCliPath: resolvePlaywrightCli(resolvedDir, process.platform)
     }),
     runWebFlow,
@@ -182364,7 +182679,7 @@ Examples:
 function registerFlowsRunCommand(flows, signals) {
   declareCommandKind(flows.command("run [pattern]"), "local", {
     kindNote: "read with --env"
-  }).description("Run flows matching [pattern], or every flow when omitted; with --env, pull missing flows from that QA Wolf environment").option("--retries <n>", "Retry each failing flow up to this many times", parseInteger("--retries", { min: 0 }), 0).option("--bail", "Stop the run after the first failure", false).option("--workers <n>", "Parallel worker count for web flows", parseInteger("--workers", { min: 1 }), 1).option("--timeout <ms>", "Default timeout for actions and assertions, in milliseconds", parseInteger("--timeout", { min: 0 }), 30000).option("--video <mode>", "Record video: on | off | retain-on-failure", parseEnum("--video", videoModes), videoDefault).option("--trace <mode>", "Record Playwright trace: on | off | retain-on-failure", parseEnum("--trace", traceModes), traceDefault).option("--har <mode>", "Record HAR network log: on | off | retain-on-failure", parseEnum("--har", harModes), harDefault).option("--har-content <mode>", "HAR response bodies: omit | full (full uses more memory)", parseEnum("--har-content", harContentModes), harContentDefault).option("--output-dir <path>", "Directory for run artifacts (videos, traces, HAR)", defaultOutputDir).option("--junit [path]", "Write a JUnit XML report (default: <output-dir>/junit-report.xml)").option("--headed", "Show the browser window instead of headless", false).option("--env <env>", "Pull and run a flow from this environment (UUID or slug) if not cached locally").option("--deps <dir>", "Use this prepared dependency directory instead of auto-installing the runtime; or set QAWOLF_RUNTIME_DIR to relocate the managed runtime").addHelpText("after", runExamples).action((pattern, opts, command) => {
+  }).description("Run flows matching [pattern], or every flow when omitted; with --env, pull missing flows from that QA Wolf environment").option("--retries <n>", "Retry each failing flow up to this many times", parseInteger("--retries", { min: 0 }), 0).option("--bail", "Stop the run after the first failure", false).option("--workers <n>", "Parallel worker count for web flows", parseInteger("--workers", { min: 1 }), 1).option("--timeout <ms>", "Default timeout for actions and assertions, in milliseconds", parseInteger("--timeout", { min: 0 }), 30000).option("--video <mode>", "Record video: on | off | retain-on-failure", parseEnum("--video", videoModes), videoDefault).option("--trace <mode>", "Record Playwright trace: on | off | retain-on-failure", parseEnum("--trace", traceModes), traceDefault).option("--har <mode>", "Record HAR network log: on | off | retain-on-failure", parseEnum("--har", harModes), harDefault).option("--har-content <mode>", "HAR response bodies: omit | full (full uses more memory)", parseEnum("--har-content", harContentModes), harContentDefault).option("--output-dir <path>", "Directory for run artifacts (videos, traces, HAR)", defaultOutputDir).option("--junit [path]", "Write a JUnit XML report (default: <output-dir>/junit-report.xml)").option("--headed", "Show the browser window instead of headless", false).option("--env <env>", "Pull and run a flow from this environment (UUID or slug) if not cached locally").option("--deps <dir>", "Use this prepared dependency directory instead of auto-installing the runtime; or set QAWOLF_RUNTIME_DIR to relocate the managed runtime").option("--no-browser-deps", "Skip installing OS-level browser dependencies (Linux --with-deps, which needs root); requires the system libraries to already be present").addHelpText("after", runExamples).action((pattern, opts, command) => {
     if (opts.env !== undefined) {
       const hybridFlags = { ...opts, env: opts.env };
       return withAuthContext(signals, (ctx) => handleHybridFlowsRun(ctx, pattern, hybridFlags))(opts, command);
@@ -182777,13 +183092,15 @@ async function handleInstallAndroid(ctx, pattern, envDir) {
 }
 
 // src/commands/install/browsers.ts
-async function handleInstallBrowsers(ctx, pattern, envDir) {
+async function handleInstallBrowsers(ctx, pattern, options) {
   const cwd = process.cwd();
   const { fs: fs9 } = ctx;
+  const { envDir, browserDeps } = options;
   return installBrowsers(ctx, pattern, {
     cwd,
     spawn: defaultSpawn,
     platform: process.platform,
+    browserDeps,
     expandPatterns: (patterns, dir) => expandPatterns(patterns, dir ?? cwd, undefined, fs9),
     peekFlowMeta: makePeekFlowMeta(fs9),
     resolvePlaywrightCliPath: async (files) => {
@@ -182848,18 +183165,27 @@ async function installAll(ctx, pattern, deps) {
   }
   return firstError;
 }
-async function handleInstall(ctx, pattern) {
+async function handleInstall(ctx, pattern, options) {
   const { fs: fs9 } = ctx;
   return installAll(ctx, pattern, {
     cwd: process.cwd(),
     expandPatterns: (patterns, cwd) => expandPatterns(patterns, cwd ?? process.cwd(), undefined, fs9),
     peekFlowMeta: makePeekFlowMeta(fs9),
     resolveDepsRoot: (files) => resolveDepsRoot({ files, fs: fs9 }),
-    installBrowsers: handleInstallBrowsers,
+    installBrowsers: (innerCtx, innerPattern, envDir) => handleInstallBrowsers(innerCtx, innerPattern, {
+      envDir,
+      browserDeps: options.browserDeps
+    }),
     installAndroid: handleInstallAndroid
   });
 }
 
+// src/commands/install/browserDepsFlag.ts
+function mergedBrowserDeps(local, command) {
+  const parent2 = command.parent?.opts().browserDeps;
+  return local && parent2 !== false;
+}
+
 // src/commands/install/clear.ts
 async function handleInstallClear(ctx, opts) {
   const dir = managedEnvBaseDir();
@@ -182887,18 +183213,22 @@ async function handleInstallClear(ctx, opts) {
 }
 
 // src/commands/install/index.ts
+var noBrowserDepsDescription = "Skip installing OS-level browser dependencies (Linux --with-deps, which needs root); requires the system libraries to already be present";
 function registerInstallCommand(program2, signals) {
-  const install = declareCommandKind(program2.command("install"), "local").description("Install every runtime dependency the project's flows need").argument("[pattern]", "Glob limiting which flows determine required dependencies").addHelpText("after", `
+  const install = declareCommandKind(program2.command("install"), "local").description("Install every runtime dependency the project's flows need").argument("[pattern]", "Glob limiting which flows determine required dependencies").option("--no-browser-deps", noBrowserDepsDescription).addHelpText("after", `
 Examples:
   $ qawolf install
   $ qawolf install "flows/checkout/**"`).action((pattern, opts, command) => {
-    return withContext(signals, (ctx) => handleInstall(ctx, pattern))(opts, command);
+    return withContext(signals, (ctx) => handleInstall(ctx, pattern, { browserDeps: opts.browserDeps }))(opts, command);
   });
-  declareCommandKind(install.command("browsers [pattern]"), "local").description("Install Playwright browsers used by the project's web flows").addHelpText("after", `
+  declareCommandKind(install.command("browsers [pattern]"), "local").description("Install Playwright browsers used by the project's web flows").option("--no-browser-deps", noBrowserDepsDescription).addHelpText("after", `
 Examples:
   $ qawolf install browsers
   $ qawolf install browsers "flows/web/**"`).action((pattern, opts, command) => {
-    return withContext(signals, (ctx) => handleInstallBrowsers(ctx, pattern))(opts, command);
+    return withContext(signals, (ctx) => handleInstallBrowsers(ctx, pattern, {
+      envDir: undefined,
+      browserDeps: mergedBrowserDeps(opts.browserDeps, command)
+    }))(opts, command);
   });
   declareCommandKind(install.command("android [pattern]"), "local").description("Install Android system images, AVDs, and the Appium driver used by the project's Android flows").addHelpText("after", `
 Examples:
@@ -182914,8 +183244,7 @@ Examples:
   });
 }
 
-// src/core/publicApi/flagSpecs.ts
-var kebabCase = (field) => field.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+// src/core/publicApi/flagKind.ts
 function flagKind(schema) {
   if (schema.type === "string")
     return { ok: true, kind: "string" };
@@ -182950,6 +183279,110 @@ function flagKind(schema) {
     reason: `type ${schema.type ?? "unknown"} cannot be expressed as a flag`
   };
 }
+
+// src/core/publicApi/objectShape.ts
+var asObjectShape = (schema) => schema.type === "object" && schema.properties ? { properties: schema.properties, required: new Set(schema.required) } : undefined;
+function mergeIntersection(members) {
+  const shape = { properties: {}, required: new Set };
+  for (const member of members) {
+    const memberShape = asObjectShape(member);
+    if (!memberShape) {
+      return {
+        ok: false,
+        field: "",
+        reason: "intersection members must be object schemas"
+      };
+    }
+    for (const [field, fieldSchema] of Object.entries(memberShape.properties)) {
+      if (field in shape.properties) {
+        return {
+          ok: false,
+          field,
+          reason: "field appears in multiple intersection members"
+        };
+      }
+      shape.properties[field] = fieldSchema;
+      if (memberShape.required.has(field))
+        shape.required.add(field);
+    }
+  }
+  return { ok: true, shape };
+}
+function mergeUnion(branches) {
+  const shapes = [];
+  for (const branch of branches) {
+    const branchShape = asObjectShape(branch);
+    if (!branchShape) {
+      return {
+        ok: false,
+        field: "",
+        reason: "union branches must be object schemas"
+      };
+    }
+    shapes.push(branchShape);
+  }
+  const shape = { properties: {}, required: new Set };
+  for (const branchShape of shapes) {
+    for (const [field, fieldSchema] of Object.entries(branchShape.properties)) {
+      const existing = shape.properties[field];
+      if (!existing) {
+        shape.properties[field] = { ...fieldSchema };
+        continue;
+      }
+      const kinds2 = [flagKind(existing), flagKind(fieldSchema)];
+      if (kinds2[0]?.ok && kinds2[1]?.ok && kinds2[0].kind !== kinds2[1].kind) {
+        return {
+          ok: false,
+          field,
+          reason: "field has conflicting types across union branches"
+        };
+      }
+      if (!existing.description && fieldSchema.description) {
+        existing.description = fieldSchema.description;
+      }
+    }
+  }
+  const discriminator = Object.keys(shape.properties).find((field) => {
+    const values = shapes.map((branch) => branch.properties[field]?.const);
+    return values.every((value) => typeof value === "string") && new Set(values).size === shapes.length && shapes.every((branch) => branch.required.has(field));
+  });
+  if (discriminator === undefined) {
+    return {
+      ok: false,
+      field: "",
+      reason: "union branches must share a literal discriminator field"
+    };
+  }
+  for (const [field, fieldSchema] of Object.entries(shape.properties)) {
+    const occurrences = shapes.filter((branch) => (field in branch.properties));
+    if (occurrences.length === shapes.length && occurrences.every((branch) => branch.required.has(field))) {
+      shape.required.add(field);
+    }
+    if (field === discriminator) {
+      const values = shapes.map((branch) => branch.properties[field]?.const);
+      fieldSchema.description = `One of: ${values.join(", ")}`;
+    }
+  }
+  return { ok: true, shape };
+}
+function toObjectShape(schema) {
+  if (schema.allOf)
+    return mergeIntersection(schema.allOf);
+  const branches = schema.oneOf ?? schema.anyOf;
+  if (branches)
+    return mergeUnion(branches);
+  const shape = asObjectShape(schema);
+  if (shape)
+    return { ok: true, shape };
+  return {
+    ok: false,
+    field: "",
+    reason: "contract input must be an object schema"
+  };
+}
+
+// src/core/publicApi/flagSpecs.ts
+var kebabCase = (field) => field.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
 function flagUsage(field, kind) {
   const name = `--${kebabCase(field)}`;
   if (kind === "boolean")
@@ -182964,16 +183397,11 @@ function buildFlagSpecs(inputSchema) {
   const jsonSchema = exports_external.toJSONSchema(inputSchema, {
     io: "input"
   });
-  if (jsonSchema.type !== "object" || !jsonSchema.properties) {
-    return {
-      ok: false,
-      field: "",
-      reason: "contract input must be an object schema"
-    };
-  }
-  const required2 = new Set(jsonSchema.required ?? []);
+  const result = toObjectShape(jsonSchema);
+  if (!result.ok)
+    return result;
   const flags = [];
-  for (const [field, fieldSchema] of Object.entries(jsonSchema.properties)) {
+  for (const [field, fieldSchema] of Object.entries(result.shape.properties)) {
     const kind = flagKind(fieldSchema);
     if (!kind.ok)
       return { ok: false, field, reason: kind.reason };
@@ -182981,7 +183409,7 @@ function buildFlagSpecs(inputSchema) {
       field,
       flag: flagUsage(field, kind.kind),
       description: fieldSchema.description ?? "",
-      required: required2.has(field),
+      required: result.shape.required.has(field),
       kind: kind.kind
     });
   }
@@ -183159,4 +183587,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=724E44C8F9B9A9E264756E2164756E21
+//# debugId=F2AE77060354D60864756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -60,7 +60,7 @@
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
     "@playwright/test": "1.60.0",
-    "@qawolf/api-contracts": "0.2.0",
+    "@qawolf/api-contracts": "0.11.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",

package/skills/qawolf-cli/SKILL.md

@@ -40,21 +40,31 @@ write on timeout: it may have reached the server the first time.
 
 <!-- commands-table:start — generated by `bun run generate`, do not edit -->
 
-| Command                   | Kind                       | What it does                                                                                                           |
-| ------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `qawolf auth login`       | local                      | Authenticate with your QA Wolf API key                                                                                 |
-| `qawolf auth logout`      | local                      | Remove stored credentials                                                                                              |
-| `qawolf auth whoami`      | read                       | Show authentication status                                                                                             |
-| `qawolf doctor`           | local                      | Diagnose problems running flows locally                                                                                |
-| `qawolf flows list`       | local (read with --remote) | List flows matching [pattern] from the local project, or from a QA Wolf environment with --remote                      |
-| `qawolf flows pull`       | read                       | Download an environment's flows into the local .qawolf/<env>/ cache                                                    |
-| `qawolf flows run`        | local (read with --env)    | Run flows matching [pattern], or every flow when omitted; with --env, pull missing flows from that QA Wolf environment |
-| `qawolf init`             | local                      | Scaffold a QA Wolf project in the current directory                                                                    |
-| `qawolf install`          | local                      | Install every runtime dependency the project's flows need                                                              |
-| `qawolf install android`  | local                      | Install Android system images, AVDs, and the Appium driver used by the project's Android flows                         |
-| `qawolf install browsers` | local                      | Install Playwright browsers used by the project's web flows                                                            |
-| `qawolf install clear`    | local                      | Remove the managed runtime cache (all installed runtime versions)                                                      |
-| `qawolf run create`       | write                      | Create a run for selected flows in an environment.                                                                     |
+| Command                                | Kind                       | What it does                                                                                                               |
+| -------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `qawolf auth login`                    | local                      | Authenticate with your QA Wolf API key                                                                                     |
+| `qawolf auth logout`                   | local                      | Remove stored credentials                                                                                                  |
+| `qawolf auth whoami`                   | read                       | Show authentication status                                                                                                 |
+| `qawolf automate`                      | write                      | Request an automation that builds the selected draft flows in an environment.                                              |
+| `qawolf doctor`                        | local                      | Diagnose problems running flows locally                                                                                    |
+| `qawolf environment create`            | write                      | Create an environment on the caller's team and return it in the environment.get shape.                                     |
+| `qawolf environment get`               | read                       | Read a single environment's name, kind, health status, and termination state.                                              |
+| `qawolf environment listVariableNames` | read                       | List the names of an environment's variables, sorted. Names only — values never leave the server.                          |
+| `qawolf flows list`                    | local (read with --remote) | List flows matching [pattern] from the local project, or from a QA Wolf environment with --remote                          |
+| `qawolf flows pull`                    | read                       | Download an environment's flows into the local .qawolf/<env>/ cache                                                        |
+| `qawolf flows run`                     | local (read with --env)    | Run flows matching [pattern], or every flow when omitted; with --env, pull missing flows from that QA Wolf environment     |
+| `qawolf init`                          | local                      | Scaffold a QA Wolf project in the current directory                                                                        |
+| `qawolf install`                       | local                      | Install every runtime dependency the project's flows need                                                                  |
+| `qawolf install android`               | local                      | Install Android system images, AVDs, and the Appium driver used by the project's Android flows                             |
+| `qawolf install browsers`              | local                      | Install Playwright browsers used by the project's web flows                                                                |
+| `qawolf install clear`                 | local                      | Remove the managed runtime cache (all installed runtime versions)                                                          |
+| `qawolf issue create`                  | write                      | Create a bug or coverage request issue for the caller's team. Maintenance issues cannot be created through the public API. |
+| `qawolf issue find`                    | read                       | List the team's bug reports, maintenance reports, or coverage requests, newest first.                                      |
+| `qawolf issue get`                     | read                       | Get an issue by id.                                                                                                        |
+| `qawolf run create`                    | write                      | Create a run for the selected flows and/or tags in an environment.                                                         |
+| `qawolf run find`                      | read                       | List an environment's recent runs, newest first.                                                                           |
+| `qawolf run get`                       | read                       | Get a run's status, per-flow results, and links.                                                                           |
+| `qawolf tag create`                    | write                      | Create a tag on the caller's team. Tags select flows in run.create.                                                        |
 
 <!-- commands-table:end -->