@dench.com/cli 2.8.1-staging.110 → 2.8.3-staging.117

package/leads.ts

@@ -0,0 +1,1035 @@
+/**
+ * `dench leads find`, `dench jobs find`, and workspace artifact
+ * list/show/import. Find writes a durable table artifact; import is the
+ * same path as the chat card.
+ */
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  assertNoUnknownFlags as assertNoUnknownFlagsRaw,
+  CliArgError,
+  getFlag,
+  hasFlag,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+import {
+  EnrichmentGatewayError,
+  type EnrichmentGatewayOptions,
+  searchCompanies,
+  searchJobs,
+  searchPeople,
+} from "./lib/enrichment-gateway";
+import { FIND_FILTER_OPTION_CATALOG } from "./lib/find-filter-options.generated";
+
+class FindCliError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FindCliError";
+  }
+}
+
+type FindCliContext = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+  sessionToken?: string;
+  enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
+};
+
+const api = {
+  saveFind: makeFunctionReference<"action">(
+    "functions/workspaceArtifacts:saveFind",
+  ),
+  updateFind: makeFunctionReference<"action">(
+    "functions/workspaceArtifacts:updateFind",
+  ),
+  rename: makeFunctionReference<"mutation">(
+    "functions/workspaceArtifacts:rename",
+  ),
+  remove: makeFunctionReference<"mutation">(
+    "functions/workspaceArtifacts:remove",
+  ),
+  list: makeFunctionReference<"query">("functions/workspaceArtifacts:list"),
+  get: makeFunctionReference<"query">("functions/workspaceArtifacts:get"),
+  importArtifact: makeFunctionReference<"action">(
+    "functions/workspaceArtifacts:importArtifact",
+  ),
+  resolveCompanyList: makeFunctionReference<"action">(
+    "functions/companyLists:resolveCompanyList",
+  ),
+};
+
+/** createdFrom values that mark an artifact as a saved search / list. */
+const LIST_CREATED_FROM = new Set([
+  "find_people",
+  "find_companies",
+  "find_jobs",
+  "mixed",
+  "watch_fire",
+]);
+
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new FindCliError(error.message);
+    throw error;
+  }
+}
+
+function assertNoUnknownFlags(args: readonly string[], command: string): void {
+  try {
+    assertNoUnknownFlagsRaw(args, command);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new FindCliError(error.message);
+    throw error;
+  }
+}
+
+type LeadsFindRange = { min?: number; max?: number };
+
+type LeadsFindFlags = {
+  titles?: string[];
+  pastTitles?: string[];
+  personNames?: string[];
+  locations?: string[];
+  seniorities?: string[];
+  industries?: string[];
+  functions?: string[];
+  subFunctions?: string[];
+  companyDomain?: string;
+  companyDomains?: string[];
+  companyNames?: string[];
+  pastCompanyNames?: string[];
+  companyHeadquarters?: string[];
+  companyTypes?: string[];
+  universities?: string[];
+  skills?: string[];
+  languages?: string[];
+  headcount?: string[];
+  yearsInRole?: LeadsFindRange;
+  yearsAtCompany?: LeadsFindRange;
+  daysSinceJobChange?: LeadsFindRange;
+  foundedYears?: LeadsFindRange;
+  keywords?: string;
+  companyList?: string;
+  limit?: number;
+  pageToken?: string;
+  name?: string;
+};
+
+/** Parse `min:max` (either side optional; a bare number means min). */
+function rangeFlag(args: string[], name: string): LeadsFindRange | undefined {
+  const raw = getFlag(args, name);
+  if (!raw) return undefined;
+  const [minRaw, maxRaw] = raw.includes(":") ? raw.split(":", 2) : [raw, ""];
+  const parsePart = (part: string, label: string): number | undefined => {
+    const trimmed = part.trim();
+    if (!trimmed) return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+      throw new FindCliError(
+        `${name} ${label} must be a non-negative integer (use min:max, e.g. 2:10)`,
+      );
+    }
+    return parsed;
+  };
+  const min = parsePart(minRaw ?? "", "min");
+  const max = parsePart(maxRaw ?? "", "max");
+  if (min === undefined && max === undefined) {
+    throw new FindCliError(`${name} must be min:max, e.g. 2:10, 2: or :10`);
+  }
+  return { min, max };
+}
+
+function parseLeadsFindFlags(args: string[]): LeadsFindFlags {
+  const flags: LeadsFindFlags = {
+    titles: csvFlag(args, "--titles"),
+    pastTitles: csvFlag(args, "--past-titles"),
+    personNames: csvFlag(args, "--person-names"),
+    locations: csvFlag(args, "--locations"),
+    seniorities: csvFlag(args, "--seniorities"),
+    industries: csvFlag(args, "--industries"),
+    functions: csvFlag(args, "--functions"),
+    subFunctions: csvFlag(args, "--sub-functions"),
+    companyDomain: getFlag(args, "--company-domain"),
+    companyDomains: csvFlag(args, "--company-domains"),
+    companyNames: csvFlag(args, "--company-names"),
+    pastCompanyNames: csvFlag(args, "--past-company-names"),
+    companyHeadquarters: csvFlag(args, "--company-hq"),
+    companyTypes: csvFlag(args, "--company-types"),
+    universities: csvFlag(args, "--universities"),
+    skills: csvFlag(args, "--skills"),
+    languages: csvFlag(args, "--languages"),
+    headcount: csvFlag(args, "--headcount"),
+    yearsInRole: rangeFlag(args, "--years-in-role"),
+    yearsAtCompany: rangeFlag(args, "--years-at-company"),
+    daysSinceJobChange: rangeFlag(args, "--days-since-job-change"),
+    foundedYears: rangeFlag(args, "--founded-years"),
+    keywords: getFlag(args, "--keywords"),
+    companyList: getFlag(args, "--company-list"),
+    limit: parseLimit(args),
+    pageToken: getFlag(args, "--page-token"),
+    name: getFlag(args, "--save-as"),
+  };
+  assertNoUnknownFlags(args, "leads find");
+  const hasFilter = Object.entries(flags).some(
+    ([key, value]) =>
+      !["limit", "pageToken", "name"].includes(key) && value !== undefined,
+  );
+  if (!hasFilter) {
+    throw new FindCliError(
+      "dench leads find requires at least one of --titles, --locations, --company-domain, --keywords, --industries, --seniorities (or any other filter flag — run `dench leads help`)",
+    );
+  }
+  return flags;
+}
+
+export function assertLeadsFindArgs(args: string[]): void {
+  const copy = [...args];
+  hasFlag(copy, "--json");
+  const verb = copy[0];
+  if (verb !== "find") return;
+  parseLeadsFindFlags(copy.slice(1));
+}
+
+function csvFlag(args: string[], name: string): string[] | undefined {
+  const raw = getFlag(args, name);
+  if (!raw) return undefined;
+  return raw
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function parseLimit(args: string[]): number | undefined {
+  const raw = getFlag(args, "--limit");
+  if (!raw) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new FindCliError("--limit must be a positive integer");
+  }
+  return Math.min(parsed, 5000);
+}
+
+function out(ctx: FindCliContext, value: unknown): void {
+  console.log(JSON.stringify(value, null, ctx.jsonOutput ? 2 : 0));
+}
+
+async function callQuery(
+  ctx: FindCliContext,
+  fn: Parameters<ConvexHttpClient["query"]>[0],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return await ctx.convex.query(fn, {
+    ...args,
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+  } as never);
+}
+
+async function callAction(
+  ctx: FindCliContext,
+  fn: Parameters<ConvexHttpClient["action"]>[0],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return await ctx.convex.action(fn, {
+    ...args,
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+  } as never);
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/* ─── Company-list filter (--company-list) ─── */
+
+type ResolvedCompanyList = {
+  source: "artifact" | "view";
+  title: string;
+  domains: string[];
+  names: string[];
+  totalCompanies: number;
+  truncated: boolean;
+};
+
+/** Convex document ids are long lowercase alphanumeric strings. */
+const COMPANY_LIST_ID_RE = /^[a-z0-9]{25,40}$/;
+
+/**
+ * `--company-list` accepts a saved-search artifact id (from
+ * `dench companies find` / `dench lists`) or a Company saved-view name.
+ * Id-shaped values are tried as artifacts first; anything else (or an
+ * id that doesn't resolve) is looked up as a view name.
+ */
+async function resolveCompanyListFlag(
+  ctx: FindCliContext,
+  value: string,
+): Promise<ResolvedCompanyList> {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new FindCliError(
+      "--company-list requires a list artifact id or a Company view name",
+    );
+  }
+  if (COMPANY_LIST_ID_RE.test(trimmed)) {
+    try {
+      return (await callAction(ctx, api.resolveCompanyList, {
+        artifactId: trimmed,
+      })) as ResolvedCompanyList;
+    } catch {
+      // Not an artifact (or not ours) — fall through to view-name lookup.
+    }
+  }
+  try {
+    return (await callAction(ctx, api.resolveCompanyList, {
+      viewName: trimmed,
+    })) as ResolvedCompanyList;
+  } catch (error) {
+    throw new FindCliError(
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
+
+/** Saved-filter entry: the reference (re-resolved on hydrate) + title. */
+function companyListFilterEntry(
+  ref: string,
+  resolved: ResolvedCompanyList,
+): Record<string, unknown> {
+  return resolved.source === "artifact"
+    ? { artifactId: ref.trim(), title: resolved.title }
+    : { viewName: ref.trim(), title: resolved.title };
+}
+
+/** Output block mirroring /api/workspace/find's `companyList` response. */
+function companyListInfo(resolved: ResolvedCompanyList) {
+  return {
+    source: resolved.source,
+    title: resolved.title,
+    companiesUsed: resolved.domains.length + resolved.names.length,
+    totalCompanies: resolved.totalCompanies,
+    truncated: resolved.truncated,
+  };
+}
+
+function mergeUnique(
+  base: string[] | undefined,
+  extra: string[] | undefined,
+): string[] | undefined {
+  const merged = [...new Set([...(base ?? []), ...(extra ?? [])])];
+  return merged.length > 0 ? merged : undefined;
+}
+
+function findTitle(
+  kind: "people" | "companies" | "jobs",
+  parts: string[],
+): string {
+  const first = parts.find((part) => part.length > 0);
+  if (kind === "people") return first ? `People: ${first}` : "People search";
+  if (kind === "companies") {
+    return first ? `Companies: ${first}` : "Company search";
+  }
+  return first ? `Jobs: ${first}` : "Job search";
+}
+
+async function persist(
+  ctx: FindCliContext,
+  args: {
+    createdFrom: "find_people" | "find_companies" | "find_jobs";
+    title: string;
+    filters: Record<string, unknown>;
+    people?: unknown[];
+    companies?: unknown[];
+    jobs?: unknown[];
+  },
+): Promise<unknown> {
+  return await callAction(ctx, api.saveFind, args);
+}
+
+export function leadsHelp(): void {
+  console.log(`Dench leads
+
+Usage:
+  dench leads find --titles "VP Sales" --locations "San Francisco" [--company-domain acme.com] [--save-as "Q3 targets"] [--limit 500] [--page-token <token>] [--json]
+  dench leads find --keywords "fintech" [--industries SaaS] [--seniorities director,vp] [--json]
+  dench leads find --company-list <artifactId|"Company view name"> --titles "VP Sales" [--json]
+  dench leads filters [--filter titles|locations|company-hq|universities|skills|keywords|seniorities|functions|sub-functions|industries|headcount|company-types|languages] [--search "query"] [--json]
+
+Filter flags (all comma-separated lists unless noted):
+  People:   --titles --past-titles --person-names --seniorities --functions
+            --sub-functions --languages --universities --skills --locations
+  Company:  --company-names --past-company-names --company-domain (single)
+            --company-domains --company-hq --company-types --industries
+            --headcount (buckets like 11-50,51-200)
+  List:     --company-list <artifactId|view name> — filter by a saved
+            company list (a \`dench companies find\` artifact or a Company
+            saved view). Resolves to the list's CURRENT companies on each
+            run; lists up to ~1000 companies are searched in one go.
+  Ranges:   --years-in-role --years-at-company --days-since-job-change
+            --founded-years   (min:max, e.g. 2:10, 2: or :10)
+  Query:    --keywords "fintech, AI"
+
+\`dench leads filters\` prints the accepted values: enum filters (seniorities,
+functions, industries, headcount, company-types, languages) expect those
+exact values; the rest are free text with curated suggestions.
+
+Finds people through Dench search and writes a workspace list artifact.
+Pass --save-as to name the list (otherwise a title is generated).
+Manage lists with \`dench lists\`; import with \`dench artifacts import <id> --to lead\`.
+Typical chain: dench companies find … --json → grab artifactId →
+dench leads find --company-list <artifactId> --titles "VP Sales".
+`);
+}
+
+/* ─── dench leads filters ─── */
+
+/** kebab-case flag spellings accepted by `--filter` alongside catalog keys. */
+const FILTER_KEY_ALIASES: Record<string, string> = {
+  "past-titles": "pastTitles",
+  "company-hq": "companyHeadquarters",
+  "company-types": "companyTypes",
+  "sub-functions": "subFunctions",
+};
+
+/**
+ * Print the Lead Finder filter-option catalogs (offline; bundled data).
+ * Enum filters list exact gateway vocabularies; suggestion filters list
+ * curated starting points — custom free text always works for those.
+ */
+export function runFindFiltersCommand(opts: {
+  args: string[];
+  jsonOutput?: boolean;
+}): void {
+  const args = [...opts.args];
+  const jsonOutput = opts.jsonOutput === true || hasFlag(args, "--json");
+  const filterRaw = getFlag(args, "--filter");
+  const search = getFlag(args, "--search")?.trim().toLowerCase();
+  assertNoUnknownFlags(args, "leads filters");
+
+  const resolveKey = (raw: string): string => {
+    const aliased = FILTER_KEY_ALIASES[raw.toLowerCase()];
+    if (aliased) return aliased;
+    const match = Object.keys(FIND_FILTER_OPTION_CATALOG).find(
+      (key) => key.toLowerCase() === raw.toLowerCase(),
+    );
+    if (match) return match;
+    throw new FindCliError(
+      `Unknown filter: ${raw}. Valid filters: ${[
+        ...Object.keys(FIND_FILTER_OPTION_CATALOG),
+        ...Object.keys(FILTER_KEY_ALIASES),
+      ].join(", ")}`,
+    );
+  };
+
+  const keys = filterRaw
+    ? [resolveKey(filterRaw)]
+    : Object.keys(FIND_FILTER_OPTION_CATALOG);
+  const filters: Record<string, unknown> = {};
+  for (const key of keys) {
+    const entry = FIND_FILTER_OPTION_CATALOG[key];
+    const groups = search
+      ? entry.groups
+          .map((group) => ({
+            group: group.group,
+            values: group.values.filter((value) =>
+              value.toLowerCase().includes(search),
+            ),
+          }))
+          .filter((group) => group.values.length > 0)
+      : entry.groups;
+    filters[key] = { label: entry.label, kind: entry.kind, groups };
+  }
+  console.log(
+    JSON.stringify(
+      {
+        note: "kind=enum values are exact gateway vocabularies; kind=suggestion values are curated starting points and custom free text is accepted.",
+        filters,
+      },
+      null,
+      jsonOutput ? 2 : 0,
+    ),
+  );
+}
+
+export function companiesHelp(): void {
+  console.log(`Dench companies
+
+Usage:
+  dench companies find --name "Acme" [--domain acme.com] [--keywords fintech] [--industries SaaS] [--locations "San Francisco"] [--linkedin https://linkedin.com/company/acme] [--save-as "Target accounts"] [--limit 500] [--page-token <token>] [--json]
+
+Finds companies through Dench search and writes a workspace list artifact.
+Pass --save-as to name the list (otherwise a title is generated).
+Manage lists with \`dench lists\`; import with \`dench artifacts import <id> --to company\`.
+The artifact id doubles as a company list: pass it to
+\`dench leads find --company-list <id>\` or \`dench jobs find --company-list <id>\`
+to search people or job postings at exactly these companies.
+`);
+}
+
+export function jobsHelp(): void {
+  console.log(`Dench jobs
+
+Usage:
+  dench jobs find --titles "Account Executive" --locations "San Francisco" [--company-domain acme.com] [--keywords remote] [--save-as "AE openings"] [--limit 500] [--page-token <token>] [--json]
+  dench jobs find --company-list <artifactId|"Company view name"> [--titles "Account Executive"] [--posted-after 2026-08-01] [--json]
+
+Company filters: --company (name), --company-domain (single),
+--company-domains (comma-separated), or --company-list (a saved company
+list: a \`dench companies find\` artifact id or a Company saved-view name —
+resolved to its current companies on each run).
+
+Finds job postings through Dench search and writes a workspace list artifact.
+Pass --save-as to name the list (otherwise a title is generated).
+Manage lists with \`dench lists\`; import with \`dench artifacts import <id> --to job_posting\`.
+`);
+}
+
+export function workspaceArtifactsHelp(): void {
+  console.log(`Dench artifacts
+
+Usage:
+  dench artifacts [--limit 25] [--json]
+  dench artifacts list [--limit 25] [--json]
+  dench artifacts show <id> [--json]
+  dench artifacts import <id> --to lead|company|job_posting [--view "Q3 outbound"] [--pin] [--json]
+
+\`list\` / \`show\` / \`import\` operate on find results (lead lists and job
+searches). Bare \`dench artifacts\` still lists agent suggested-work artifacts.
+Rename/delete saved searches with \`dench lists rename|delete\`.
+`);
+}
+
+export function listsHelp(): void {
+  console.log(`Dench lists
+
+Usage:
+  dench lists [--limit 25] [--json]
+  dench lists show <id> [--json]
+  dench lists rename <id> "New name" [--json]
+  dench lists update <id> [--title "New name"] [--filters-json '{"titles":["CTO"]}'] [--json]
+  dench lists delete <id> [--json]
+
+Lists are saved searches from Find (people / companies / job postings).
+Create one with \`dench leads|companies|jobs find --save-as "Name"\`.
+Delete removes the list, its exported CSV/JSONL files, and any linked watch.
+CRM lists (saved views on Leads/Companies/Job Postings) are managed with
+\`dench crm views list|get|create|rename|delete\`.
+`);
+}
+
+/**
+ * `dench lists …` — full management of saved searches. Returns false
+ * only for `help` so the caller can print usage.
+ */
+export async function runListsCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput?: boolean;
+  sessionToken?: string;
+}): Promise<boolean> {
+  const args = [...opts.args];
+  const ctx: FindCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput: opts.jsonOutput === true || hasFlag(args, "--json"),
+    sessionToken: opts.sessionToken,
+  };
+  const verb = args[0];
+  if (verb === "help" || verb === "--help") return false;
+  if (verb === undefined || verb === "list" || verb?.startsWith("--")) {
+    if (verb === "list") args.shift();
+    const limitRaw = getFlag(args, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : 25;
+    assertNoUnknownFlags(args, "lists");
+    const rows = (await callQuery(ctx, api.list, {
+      kind: "table",
+      // Over-fetch: the query filters by kind only; saved searches are
+      // the table artifacts whose createdFrom is a find/watch source.
+      limit: Math.min(Math.max(limit * 2, limit), 200),
+    })) as Array<Record<string, unknown>>;
+    const lists = rows
+      .filter((row) => LIST_CREATED_FROM.has(String(row.createdFrom)))
+      .slice(0, limit)
+      .map((row) => ({
+        _id: row._id,
+        title: row.title,
+        createdFrom: row.createdFrom,
+        rowCount: row.rowCount,
+        createdAt: row.createdAt,
+        watchId: row.watchId,
+      }));
+    out(ctx, lists);
+    return true;
+  }
+  args.shift();
+  if (verb === "show") {
+    const artifactId = shift(args, "list id");
+    assertNoUnknownFlags(args, "lists show");
+    out(ctx, await callQuery(ctx, api.get, { artifactId }));
+    return true;
+  }
+  if (verb === "rename") {
+    const artifactId = shift(args, "list id");
+    const title = getFlag(args, "--title") ?? shift(args, "new name");
+    assertNoUnknownFlags(args, "lists rename");
+    out(
+      ctx,
+      await ctx.convex.mutation(api.rename, {
+        artifactId,
+        title,
+        ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+      } as never),
+    );
+    return true;
+  }
+  if (verb === "update") {
+    const artifactId = shift(args, "list id");
+    const title = getFlag(args, "--title");
+    const filtersJson = getFlag(args, "--filters-json");
+    assertNoUnknownFlags(args, "lists update");
+    let filters: unknown;
+    if (filtersJson !== undefined) {
+      try {
+        filters = JSON.parse(filtersJson);
+      } catch {
+        throw new FindCliError("--filters-json must be valid JSON");
+      }
+    }
+    if (title === undefined && filters === undefined) {
+      throw new FindCliError(
+        "dench lists update requires --title and/or --filters-json",
+      );
+    }
+    out(
+      ctx,
+      await callAction(ctx, api.updateFind, {
+        artifactId,
+        ...(title !== undefined ? { title } : {}),
+        ...(filters !== undefined ? { filters } : {}),
+      }),
+    );
+    return true;
+  }
+  if (verb === "delete") {
+    const artifactId = shift(args, "list id");
+    assertNoUnknownFlags(args, "lists delete");
+    out(
+      ctx,
+      await ctx.convex.mutation(api.remove, {
+        artifactId,
+        ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+      } as never),
+    );
+    return true;
+  }
+  throw new FindCliError(
+    `Unknown lists verb: ${verb}. Try list, show, rename, update, delete.`,
+  );
+}
+
+export function assertJobsFindArgs(args: string[]): void {
+  const copy = [...args];
+  hasFlag(copy, "--json");
+  if (copy[0] !== "find") return;
+  if (
+    !copy.includes("--titles") &&
+    !copy.includes("--locations") &&
+    !copy.includes("--company-domain") &&
+    !copy.includes("--company-domains") &&
+    !copy.includes("--company") &&
+    !copy.includes("--company-list") &&
+    !copy.includes("--keywords")
+  ) {
+    throw new FindCliError(
+      "dench jobs find requires at least one of --titles, --locations, --company-domain, --company-domains, --company, --company-list, --keywords",
+    );
+  }
+}
+
+export function assertCompaniesFindArgs(args: string[]): void {
+  const copy = [...args];
+  hasFlag(copy, "--json");
+  if (copy[0] !== "find") return;
+  if (
+    !copy.includes("--domain") &&
+    !copy.includes("--name") &&
+    !copy.includes("--keywords") &&
+    !copy.includes("--industries") &&
+    !copy.includes("--locations") &&
+    !copy.includes("--linkedin") &&
+    !copy.includes("--headcount")
+  ) {
+    throw new FindCliError(
+      "dench companies find requires at least one of --name, --domain, --keywords, --industries, --locations, --linkedin, --headcount",
+    );
+  }
+}
+
+export async function runLeadsCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput?: boolean;
+  sessionToken?: string;
+  enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonFromArgs = hasFlag(args, "--json");
+  const ctx: FindCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput: opts.jsonOutput === true || jsonFromArgs,
+    sessionToken: opts.sessionToken,
+    enrichmentGateway: opts.enrichmentGateway,
+  };
+  const verb = args.shift();
+  if (!verb || verb === "help" || verb === "--help") {
+    leadsHelp();
+    return;
+  }
+  if (verb === "filters") {
+    runFindFiltersCommand({ args, jsonOutput: ctx.jsonOutput });
+    return;
+  }
+  if (verb !== "find") {
+    throw new FindCliError(`Unknown leads verb: ${verb}`);
+  }
+  const { name: listName, ...flags } = parseLeadsFindFlags(args);
+  // Resolve --company-list fresh per search so the filter tracks the
+  // list's CURRENT companies (domains exact, name fallback for rows
+  // without a domain).
+  const companyList = flags.companyList
+    ? await resolveCompanyListFlag(ctx, flags.companyList)
+    : undefined;
+  try {
+    const result = await searchPeople(
+      {
+        titles: flags.titles,
+        pastTitles: flags.pastTitles,
+        personNames: flags.personNames,
+        locations: flags.locations,
+        seniorities: flags.seniorities,
+        jobFunctions: flags.functions,
+        subFunctions: flags.subFunctions,
+        industries: flags.industries,
+        organizationDomains: flags.companyDomain
+          ? [flags.companyDomain]
+          : undefined,
+        companyDomains: mergeUnique(flags.companyDomains, companyList?.domains),
+        companyNames: mergeUnique(flags.companyNames, companyList?.names),
+        pastCompanyNames: flags.pastCompanyNames,
+        companyHeadquarters: flags.companyHeadquarters,
+        companyTypes: flags.companyTypes,
+        universities: flags.universities,
+        skills: flags.skills,
+        languages: flags.languages,
+        headcountRanges: flags.headcount,
+        yearsInRole: flags.yearsInRole,
+        yearsAtCompany: flags.yearsAtCompany,
+        daysSinceJobChange: flags.daysSinceJobChange,
+        foundedYears: flags.foundedYears,
+        keywords: flags.keywords,
+        limit: flags.limit,
+        pageToken: flags.pageToken,
+      },
+      ctx.enrichmentGateway,
+    );
+    const people = asArray(result.people);
+    // Persist every set filter so the saved list hydrates the full rail.
+    const savedFilters: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(flags)) {
+      if (key === "pageToken" || value === undefined) continue;
+      savedFilters[key] = value;
+    }
+    if (flags.companyList && companyList) {
+      // Store the reference (not the resolved domains) so re-running the
+      // saved search picks up the list's contents at that time.
+      savedFilters.companyList = companyListFilterEntry(
+        flags.companyList,
+        companyList,
+      );
+    }
+    const artifact = await persist(ctx, {
+      createdFrom: "find_people",
+      title:
+        listName ??
+        findTitle("people", [
+          flags.titles?.[0] ?? "",
+          flags.keywords ?? "",
+          flags.companyDomain ?? "",
+          companyList?.title ?? "",
+        ]),
+      filters: savedFilters,
+      people,
+    });
+    // metadata carries total / nextPageToken — pass the token back via
+    // --page-token to continue where this page stopped.
+    out(ctx, {
+      ...(artifact as Record<string, unknown>),
+      metadata: result.metadata,
+      ...(companyList ? { companyList: companyListInfo(companyList) } : {}),
+    });
+  } catch (error) {
+    throw new FindCliError(
+      error instanceof EnrichmentGatewayError || error instanceof Error
+        ? error.message
+        : String(error),
+    );
+  }
+}
+
+export async function runJobsCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput?: boolean;
+  sessionToken?: string;
+  enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonFromArgs = hasFlag(args, "--json");
+  const ctx: FindCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput: opts.jsonOutput === true || jsonFromArgs,
+    sessionToken: opts.sessionToken,
+    enrichmentGateway: opts.enrichmentGateway,
+  };
+  const verb = args.shift();
+  if (!verb || verb === "help" || verb === "--help") {
+    jobsHelp();
+    return;
+  }
+  if (verb !== "find") {
+    throw new FindCliError(`Unknown jobs verb: ${verb}`);
+  }
+  const titles = csvFlag(args, "--titles");
+  const locations = csvFlag(args, "--locations");
+  const companyDomain = getFlag(args, "--company-domain");
+  const companyDomains = csvFlag(args, "--company-domains");
+  const companyName = getFlag(args, "--company");
+  const keywords = getFlag(args, "--keywords");
+  const postedAfter = getFlag(args, "--posted-after");
+  const companyListRef = getFlag(args, "--company-list");
+  const limit = parseLimit(args);
+  const pageToken = getFlag(args, "--page-token");
+  const listName = getFlag(args, "--save-as");
+  assertNoUnknownFlags(args, "jobs find");
+  if (
+    !titles &&
+    !locations &&
+    !companyDomain &&
+    !companyDomains &&
+    !companyName &&
+    !keywords &&
+    !companyListRef
+  ) {
+    throw new FindCliError(
+      "dench jobs find requires at least one of --titles, --locations, --company-domain, --company-domains, --company, --company-list, --keywords",
+    );
+  }
+  const companyList = companyListRef
+    ? await resolveCompanyListFlag(ctx, companyListRef)
+    : undefined;
+  try {
+    const result = await searchJobs(
+      {
+        titles,
+        locations,
+        companyDomain,
+        companyDomains: mergeUnique(companyDomains, companyList?.domains),
+        companyName,
+        companyNames: companyList?.names.length ? companyList.names : undefined,
+        keywords,
+        postedAfter,
+        limit,
+        pageToken,
+      },
+      ctx.enrichmentGateway,
+    );
+    const jobs = asArray(result.jobs);
+    const artifact = await persist(ctx, {
+      createdFrom: "find_jobs",
+      title:
+        listName ??
+        findTitle("jobs", [
+          titles?.[0] ?? "",
+          companyName ?? "",
+          keywords ?? "",
+          companyList?.title ?? "",
+        ]),
+      filters: {
+        titles,
+        locations,
+        companyDomain,
+        companyDomains,
+        companyName,
+        keywords,
+        postedAfter,
+        limit,
+        ...(companyListRef && companyList
+          ? {
+              companyList: companyListFilterEntry(companyListRef, companyList),
+            }
+          : {}),
+      },
+      jobs,
+    });
+    out(ctx, {
+      ...(artifact as Record<string, unknown>),
+      metadata: result.metadata,
+      ...(companyList ? { companyList: companyListInfo(companyList) } : {}),
+    });
+  } catch (error) {
+    throw new FindCliError(
+      error instanceof EnrichmentGatewayError || error instanceof Error
+        ? error.message
+        : String(error),
+    );
+  }
+}
+
+export async function runCompaniesCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput?: boolean;
+  sessionToken?: string;
+  enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonFromArgs = hasFlag(args, "--json");
+  const ctx: FindCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput: opts.jsonOutput === true || jsonFromArgs,
+    sessionToken: opts.sessionToken,
+    enrichmentGateway: opts.enrichmentGateway,
+  };
+  const verb = args.shift();
+  if (!verb || verb === "help" || verb === "--help") {
+    companiesHelp();
+    return;
+  }
+  if (verb !== "find") {
+    throw new FindCliError(`Unknown companies verb: ${verb}`);
+  }
+  const domain = getFlag(args, "--domain");
+  const name = getFlag(args, "--name");
+  const keywords = getFlag(args, "--keywords");
+  const industries = csvFlag(args, "--industries");
+  const locations = csvFlag(args, "--locations");
+  const linkedinUrl = getFlag(args, "--linkedin");
+  const headcountRanges = csvFlag(args, "--headcount");
+  const limit = parseLimit(args);
+  const pageToken = getFlag(args, "--page-token");
+  const listName = getFlag(args, "--save-as");
+  assertNoUnknownFlags(args, "companies find");
+  if (
+    !domain &&
+    !name &&
+    !keywords &&
+    !industries &&
+    !locations &&
+    !linkedinUrl &&
+    !headcountRanges
+  ) {
+    throw new FindCliError(
+      "dench companies find requires at least one of --name, --domain, --keywords, --industries, --locations, --linkedin, --headcount",
+    );
+  }
+  try {
+    const result = await searchCompanies(
+      {
+        domain,
+        name,
+        keywords,
+        industries,
+        locations,
+        linkedinUrl,
+        headcountRanges,
+        limit,
+        pageToken,
+      },
+      ctx.enrichmentGateway,
+    );
+    const artifact = await persist(ctx, {
+      createdFrom: "find_companies",
+      title:
+        listName ??
+        findTitle("companies", [name ?? "", domain ?? "", keywords ?? ""]),
+      filters: {
+        domain,
+        name,
+        keywords,
+        industries,
+        locations,
+        linkedinUrl,
+        headcountRanges,
+        limit,
+      },
+      companies: asArray(result.companies),
+    });
+    out(ctx, {
+      ...(artifact as Record<string, unknown>),
+      metadata: result.metadata,
+    });
+  } catch (error) {
+    throw new FindCliError(
+      error instanceof EnrichmentGatewayError || error instanceof Error
+        ? error.message
+        : String(error),
+    );
+  }
+}
+
+export async function runWorkspaceArtifactsCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput?: boolean;
+  sessionToken?: string;
+}): Promise<boolean> {
+  const args = [...opts.args];
+  const verb = args[0];
+  if (verb !== "list" && verb !== "show" && verb !== "import") {
+    return false;
+  }
+  args.shift();
+  const ctx: FindCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput: opts.jsonOutput === true || hasFlag(args, "--json"),
+    sessionToken: opts.sessionToken,
+  };
+  if (verb === "list") {
+    const limitRaw = getFlag(args, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : 25;
+    assertNoUnknownFlags(args, "artifacts list");
+    out(ctx, await callQuery(ctx, api.list, { limit }));
+    return true;
+  }
+  if (verb === "show") {
+    const artifactId = shift(args, "artifact id");
+    assertNoUnknownFlags(args, "artifacts show");
+    out(ctx, await callQuery(ctx, api.get, { artifactId }));
+    return true;
+  }
+  const artifactId = shift(args, "artifact id");
+  const to = getFlag(args, "--to");
+  if (to !== "lead" && to !== "job_posting" && to !== "company") {
+    throw new FindCliError(
+      "dench artifacts import <id> --to lead|company|job_posting [--view ...] [--pin]",
+    );
+  }
+  const viewName = getFlag(args, "--view");
+  const pin = hasFlag(args, "--pin");
+  assertNoUnknownFlags(args, "artifacts import");
+  out(
+    ctx,
+    await callAction(ctx, api.importArtifact, {
+      artifactId,
+      to,
+      viewName,
+      pin,
+    }),
+  );
+  return true;
+}