open-local-audit 0.68.0 → 0.69.0

package/dist/start.js

@@ -0,0 +1,234 @@
+import { lstat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+const categories = [
+    { query: "dental", profile: "dental" },
+    { query: "restaurant", profile: "restaurant" },
+    { query: "beauty", profile: "beauty" },
+    { query: "hotel", profile: "hotel" },
+    { query: "gym", profile: "gym" }
+];
+const overtureCategoryPattern = /^[a-z][a-z0-9_]{0,80}$/i;
+function defaultPromptIo() {
+    const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const reader = isTTY ? createInterface({ input: process.stdin, output: process.stdout, terminal: true }) : undefined;
+    let closed = false;
+    const close = () => {
+        if (!closed) {
+            closed = true;
+            reader?.close();
+        }
+    };
+    reader?.on("SIGINT", close);
+    return {
+        isTTY,
+        question: async (prompt) => {
+            if (!reader || closed)
+                return null;
+            return new Promise((answer) => {
+                const finish = (value) => {
+                    reader.off("close", onClose);
+                    answer(value);
+                };
+                const onClose = () => finish(null);
+                reader.once("close", onClose);
+                reader.question(prompt).then((value) => finish(value), () => finish(null));
+            });
+        },
+        write: (message) => process.stdout.write(message),
+        close,
+        cwd: () => process.cwd(),
+        exists: async (path) => {
+            try {
+                await lstat(path);
+                return true;
+            }
+            catch (error) {
+                if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+                    return false;
+                throw error;
+            }
+        },
+        now: () => new Date()
+    };
+}
+async function answer(io, prompt) {
+    try {
+        return await io.question(prompt);
+    }
+    catch {
+        return null;
+    }
+}
+function writeLine(io, message) {
+    io.write(`${message}\n`);
+}
+function slug(value) {
+    const normalized = value
+        .normalize("NFKD")
+        .replace(/\p{M}/gu, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return normalized || "search";
+}
+function timestamp(value) {
+    const pad = (part) => String(part).padStart(2, "0");
+    return `${value.getUTCFullYear()}${pad(value.getUTCMonth() + 1)}${pad(value.getUTCDate())}-${pad(value.getUTCHours())}${pad(value.getUTCMinutes())}${pad(value.getUTCSeconds())}`;
+}
+async function promptCountry(io) {
+    for (;;) {
+        const value = await answer(io, "Country ISO code (two letters): ");
+        if (value === null)
+            return null;
+        const country = value.trim().toUpperCase();
+        if (/^[A-Z]{2}$/.test(country))
+            return country;
+        writeLine(io, "Country must use a two-letter ISO code, for example TR.");
+    }
+}
+async function promptCity(io) {
+    for (;;) {
+        const value = await answer(io, "City: ");
+        if (value === null)
+            return null;
+        const city = value.trim();
+        if (city)
+            return city;
+        writeLine(io, "City is required.");
+    }
+}
+async function promptCategory(io) {
+    writeLine(io, "Category: 1) dental  2) restaurant  3) beauty  4) hotel  5) gym  6) custom Overture category");
+    for (;;) {
+        const selected = await answer(io, "Choose a category [1-6]: ");
+        if (selected === null)
+            return null;
+        if (!/^[1-6]$/.test(selected.trim())) {
+            writeLine(io, "Choose a category number from 1 to 6.");
+            continue;
+        }
+        const index = Number(selected.trim()) - 1;
+        if (index < categories.length)
+            return categories[index];
+        for (;;) {
+            const custom = await answer(io, "Custom Overture category: ");
+            if (custom === null)
+                return null;
+            const query = custom.trim();
+            if (overtureCategoryPattern.test(query))
+                return { query, profile: "generic" };
+            writeLine(io, "Use an Overture category identifier beginning with a letter and containing only letters, digits, or underscores.");
+        }
+    }
+}
+async function promptWholeNumber(io, prompt, defaultValue, minimum, maximum, invalidMessage) {
+    for (;;) {
+        const input = await answer(io, `${prompt} [${defaultValue}]: `);
+        if (input === null)
+            return null;
+        const value = input.trim();
+        if (!value)
+            return defaultValue;
+        if (/^(?:0|[1-9]\d*)$/.test(value)) {
+            const parsed = Number(value);
+            if (Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum)
+                return parsed;
+        }
+        writeLine(io, invalidMessage);
+    }
+}
+async function uniqueDefaultDirectory(io, country, city, category) {
+    const base = resolve(io.cwd(), "reports", `${country.toLowerCase()}-${slug(city)}-${slug(category)}-${timestamp(io.now())}`);
+    let candidate = base;
+    let suffix = 2;
+    while (await io.exists(candidate)) {
+        candidate = `${base}-${suffix}`;
+        suffix += 1;
+    }
+    return candidate;
+}
+async function promptOutputDirectory(io, defaultDirectory) {
+    for (;;) {
+        const input = await answer(io, `Output directory [${defaultDirectory}]: `);
+        if (input === null)
+            return null;
+        const directory = input.trim() ? resolve(io.cwd(), input.trim()) : defaultDirectory;
+        if (!await io.exists(directory))
+            return directory;
+        writeLine(io, "Output path already exists. Choose a new directory so existing results are not overwritten.");
+    }
+}
+function showSummary(io, options) {
+    writeLine(io, "");
+    writeLine(io, "Discovery summary");
+    writeLine(io, `  Location: ${options.city}, ${options.country}`);
+    writeLine(io, `  Category: ${options.query}`);
+    writeLine(io, `  Candidate limit: ${options.limit}`);
+    writeLine(io, `  Website audit cap: ${options.maxAudits}`);
+    writeLine(io, `  Output: ${options.outDir}`);
+    writeLine(io, "  Free API-keyless Overture discovery; results are stored in local files.");
+}
+export async function collectStartOptions(io = defaultPromptIo()) {
+    try {
+        if (!io.isTTY) {
+            throw new Error("Interactive start requires a terminal. Use discover dental --city Istanbul --country TR --dry-run --export-csv leads.csv instead.");
+        }
+        const country = await promptCountry(io);
+        if (country === null)
+            return null;
+        const city = await promptCity(io);
+        if (city === null)
+            return null;
+        const category = await promptCategory(io);
+        if (category === null)
+            return null;
+        const limit = await promptWholeNumber(io, "Candidate count", 10, 1, 100, "Candidate count must be a whole number from 1 to 100.");
+        if (limit === null)
+            return null;
+        const maxAudits = await promptWholeNumber(io, "Website audit cap", Math.min(3, limit), 0, limit, `Website audit cap must be a whole number from 0 to ${limit}.`);
+        if (maxAudits === null)
+            return null;
+        const defaultDirectory = await uniqueDefaultDirectory(io, country, city, category.query);
+        let outDir = await promptOutputDirectory(io, defaultDirectory);
+        if (outDir === null)
+            return null;
+        for (;;) {
+            showSummary(io, { city, country, query: category.query, limit, maxAudits, outDir });
+            const confirmation = await answer(io, "Start? [Y/n]: ");
+            if (confirmation === null)
+                return null;
+            const normalized = confirmation.trim().toLowerCase();
+            if (!normalized || normalized === "y" || normalized === "yes") {
+                if (!await io.exists(outDir)) {
+                    return {
+                        provider: "overture",
+                        query: category.query,
+                        city,
+                        country,
+                        profile: category.profile,
+                        limit,
+                        maxAudits,
+                        concurrency: 3,
+                        dryRun: maxAudits === 0,
+                        outDir,
+                        exportCsv: join(outDir, "leads.csv"),
+                        summaryJson: join(outDir, "discovery-summary.json")
+                    };
+                }
+                writeLine(io, "Output path already exists. Choose a new directory so existing results are not overwritten.");
+                outDir = await promptOutputDirectory(io, defaultDirectory);
+                if (outDir === null)
+                    return null;
+                continue;
+            }
+            if (normalized === "n" || normalized === "no")
+                return null;
+            writeLine(io, "Please answer Y or n.");
+        }
+    }
+    finally {
+        io.close();
+    }
+}
+//# sourceMappingURL=start.js.map

package/dist/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":"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"}

package/dist/workflow-config.d.ts

@@ -158,7 +158,6 @@ declare const workflowConfigSchema: z.ZodObject<{
     packageReports: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     outDir: string;
-    version: 1;
     discovery: {
         profile: "generic" | "dental" | "beauty" | "restaurant" | "contractor" | "lawyer" | "clinic" | "gym" | "hotel" | "auto-service";
         input: string;
@@ -182,6 +181,7 @@ declare const workflowConfigSchema: z.ZodObject<{
         release?: string | undefined;
         maxAudits?: number | undefined;
     };
+    version: 1;
     shortlist: {
         sort: "opportunity-desc" | "score-desc" | "company-asc" | "last-reviewed-asc" | "contact-confidence-desc" | "priority-desc" | "source-asc";
         top: number;
@@ -215,7 +215,6 @@ declare const workflowConfigSchema: z.ZodObject<{
     } | undefined;
 }, {
     outDir: string;
-    version: 1;
     discovery: {
         input: string;
         provider: "manual-csv";
@@ -239,6 +238,7 @@ declare const workflowConfigSchema: z.ZodObject<{
         limit?: number | undefined;
         maxAudits?: number | undefined;
     };
+    version: 1;
     shortlist: {
         profile?: string | undefined;
         sort?: "opportunity-desc" | "score-desc" | "company-asc" | "last-reviewed-asc" | "contact-confidence-desc" | "priority-desc" | "source-asc" | undefined;

package/docs/guides/free-discovery.md

@@ -4,6 +4,14 @@ The `overture` provider finds business candidates without an API key, payment ac
 
 ## Search by category and location
 
+For a guided first search from a built source checkout:
+
+```bash
+node dist/cli.js start
+```
+
+The terminal asks for a country code, city, category, candidate count, website-audit cap, and output directory. It previews the search before confirmation. Enter `n` at confirmation or press Ctrl+C to cancel. No discovery requests or output files are created before confirmation. Existing output directories are refused to protect earlier results. Piped/non-interactive use exits with an error and an explicit `discover` example; use that command in scripts.
+
 From a source checkout, install dependencies and build:
 
 Use Node.js 22.19 or newer.
@@ -26,6 +34,26 @@ node dist/cli.js discover beauty --bbox "28.85,40.95,29.10,41.10" --profile beau
 
 Friendly categories include `dental`, `restaurant`, `beauty`, `hotel`, and `gym`; official Overture taxonomy identifiers also work. Matching includes descendants. `--profile` selects existing audit rules separately from the discovery category. No matches do not prove no businesses exist in the area.
 
+## Repeated-search cache
+
+`discover` with Overture and `start` enable the local business-result cache by default. An entry is reusable only for the same normalized category, numeric bounding box, candidate limit, and Overture release, and for at most seven days. A different audit profile reuses source data with the newly selected profile. Website audits are never taken from this cache; they run again up to the requested audit cap.
+
+Without `--release`, the current Overture release is checked before looking in the cache. This still needs a small network request; an old cached release is not silently used if the release lookup fails. A pinned `--release` can reuse its valid cache without querying STAC or the remote Places files. Cached results keep their original retrieval time; neither that time nor the release date means the business details were independently verified.
+
+- `--refresh-cache` bypasses the saved result and replaces that search's entry after a successful lookup.
+- `--no-cache` disables business-result cache reads and writes.
+- `--cache-dir <path>` selects another directory; relative paths resolve from the current working directory. It cannot be combined with `--no-cache`.
+
+```bash
+node dist/cli.js discover dental --city Istanbul --country TR --profile dental --limit 10 --dry-run --cache-dir reports/search-cache --export-csv reports/leads.csv
+```
+
+The CLI reports `hit`, `miss`, `refresh`, `disabled`, or `unavailable`, alongside the source release and original fetch time when available. Invalid, expired, oversized, or unsafe entries do not become cache hits. Cache storage failures fall back to a fresh search with a diagnostic; an actual source-search failure remains an error.
+
+Default storage is `%LOCALAPPDATA%/open-local-audit/cache/discovery` on Windows, `~/Library/Caches/open-local-audit/discovery` on macOS, and `$XDG_CACHE_HOME/open-local-audit/discovery` (or `~/.cache/open-local-audit/discovery`) on Linux. It contains public source business details, not API keys or website audit reports. Each entry is limited to 2 MiB; expired entries are replaced when searched again, rather than removed by a background job.
+
+The existing GeoNames city-file cache remains separate under the output directory. Programmatic discovery opts into business caching with `cacheDir`; the version-1 `workflow` command keeps its existing uncached execution and output contract.
+
 ## Data and limits
 
 - Overture cloud GeoParquet is queried using local DuckDB. First use installs its `httpfs` extension and requires network access to the extension repository, Overture STAC and S3. A full-world dataset is not intentionally downloaded.
@@ -78,6 +106,14 @@ npm run benchmark:discovery -- --out-dir reports/free-discovery-benchmark
 
 The default 24-search matrix uses Istanbul/Ankara (Türkiye), New York/Los Angeles (USA), Berlin/Munich (Germany), and London/Manchester (UK), each for dental, restaurant, and beauty. These are major-city samples, not an official popularity ranking. Every search uses a documented city-centre box, up to ten candidates, up to three website audits, and concurrency three. The first returned release is pinned for later searches.
 
+The benchmark leaves business caching disabled unless `--cache-dir` is explicitly supplied, preserving fresh-search measurements. To compare the same search before and after caching, use a new cache directory and inspect the recorded `miss`/`hit` states:
+
+```bash
+npm run benchmark:discovery -- --out-dir reports/cache-benchmark --cache-dir reports/cache-benchmark/first-cache --case-filter tr-istanbul-dental --repeats 2 --max-audits 0 --release 2026-09-23.1
+```
+
+`--max-audits 0` isolates discovery from website work. A previously populated cache may produce a hit on both runs; do not label the first run cold unless its recorded state is `miss`. Per-case JSON retains cache state and original fetch time; the CSV and Markdown identify cached runs. A single pair is an indicative measurement, not a speed guarantee or a load test.
+
 Case JSON and prospect/report outputs are saved as each case completes, followed by summary JSON, CSV, and Markdown. Failure times remain in the evidence. Discovery and enrichment/report times are separate. Contact completeness among returned rows is not market coverage, recall, or contact correctness. Percentiles across different scenarios are descriptive, not load-test results or an SLA. One pass does not establish stable latency. Use `--repeats 2` to intentionally measure another pass, or `--case-filter Istanbul` to limit the matrix.
 
 ## Sources and attribution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-local-audit",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Open-source website and local presence auditor for small businesses.",
   "license": "MIT",
   "type": "module",