open-local-audit 0.62.0 → 0.64.0

package/docs/architecture/workflow-plan.md

@@ -0,0 +1,229 @@
+# Workflow Plan
+
+## Purpose
+
+Workflow plan explains what a version `1` workflow would run, in which order, with which effective settings, and which local artifacts it would read or write. It includes the existing readiness checks without running discovery or changing workflow outputs.
+
+```bash
+open-local-audit workflow --config workflow.json --plan
+open-local-audit workflow --config workflow.json --plan --format json
+```
+
+`--check` answers whether a workflow is ready to run. `--plan` includes that readiness result and adds an explainable execution plan. The two options are mutually exclusive. `--format terminal|json` is accepted with either option and remains invalid for normal workflow execution.
+
+## Goals
+
+- Show the successful-path workflow steps and their dependencies.
+- Explain configured, conditional, and disabled steps.
+- Show sanitized effective settings and deterministic local artifact paths.
+- Identify steps that can call Google Places or audited websites.
+- Report configuration-derived work limits without presenting them as predicted usage or currency cost.
+- Preserve the existing preflight and workflow execution contracts.
+
+## Non-Goals
+
+Workflow plan does not:
+
+- call Google Places, audited websites, or any other network service;
+- create, replace, or delete files or directories;
+- parse lead rows to predict actual candidate, shortlist, or package counts;
+- estimate Google billing, elapsed time, or report success;
+- expose a Google query, API key, environment value, CSV contents, or raw configuration;
+- reserve output paths or remove the need for write-time containment checks;
+- resume, retry, or execute any workflow step.
+
+## Plan Model
+
+The plan lists these stable step identifiers:
+
+1. `discovery`
+2. `shortlist`
+3. `review`
+4. `packaging`
+5. `summary`
+
+Each step has one of these states:
+
+- `will-run`: the step is configured on the normal successful execution path;
+- `conditional`: the step is configured but also depends on runtime results;
+- `disabled`: the step is not enabled by the configuration.
+
+`will-run` does not guarantee execution after an earlier step fails. Normal workflow fail-fast behavior remains authoritative. Packaging is `conditional` when enabled because only selected leads with successful report artifacts can be packaged. Summary is `will-run` for a valid configuration and represents the managed workflow summary lifecycle.
+
+Dependencies describe ordering, not concurrency:
+
+- discovery has no dependency;
+- shortlist depends on discovery;
+- enabled review depends on shortlist;
+- enabled packaging depends on review when review is enabled, otherwise on shortlist;
+- summary depends on the last enabled step.
+
+Disabled steps have no dependencies. Conditional and disabled steps include a human-readable `reason`; consumers use `state`, not `reason`, for automation. Disabled steps remain in the plan so operators can see why they are absent from execution.
+
+## Effective Settings
+
+The plan reports only settings needed to explain execution:
+
+- discovery provider, audit profile, concurrency, candidate limit, and website audit cap;
+- shortlist top count, minimum opportunity score, and sort mode;
+- review stale-before date when review is configured;
+- whether report packaging is enabled.
+
+The Google Places query is intentionally omitted. A missing numeric cap is represented as `null`, meaning the configuration does not set that cap; it does not predict unlimited successful work.
+
+Network access is declared per step with stable values:
+
+- `google-places` for Google Places provider calls;
+- `website-audits` for website audit calls;
+- an empty list for local-only steps.
+
+Manual CSV discovery does not call a discovery provider, but its discovery step can still perform website audits. A zero website audit cap removes `website-audits` from that step. Plan generation itself never performs either kind of network access.
+
+## Artifact Paths
+
+The plan uses stable artifact identifiers and absolute normalized paths. It can include:
+
+- `manual-input-csv` for the manual discovery input;
+- `review-csv` for optional review state;
+- `leads-csv` and `discovery-summary-json`;
+- `reports-dir` for managed audit reports;
+- `shortlist-csv` and `shortlist-summary-json`;
+- `review-summary-json` when review is configured;
+- `packages-dir` when packaging is enabled;
+- `workflow-summary-json`.
+
+Step inputs and outputs refer to artifact identifiers instead of repeating paths. The plan does not inspect or include artifact contents.
+
+Artifact inputs and outputs follow the runtime data flow:
+
+- Discovery reads `manual-input-csv` for manual discovery and reads `review-csv` whenever review is configured. When review is configured, discovery also rewrites `review-csv`; discovery always writes `leads-csv`, `discovery-summary-json`, and `reports-dir`.
+- Shortlist always reads `leads-csv` and also reads `review-csv` when configured; it writes `shortlist-csv` and `shortlist-summary-json`.
+- Review reads only `review-csv` and writes `review-summary-json`.
+- Packaging reads report files through `reports-dir`; it uses the in-memory shortlist result and does not read `shortlist-csv`.
+
+## Result Contract
+
+The plan report is versioned independently from the workflow configuration and preflight report:
+
+```json
+{
+  "version": 1,
+  "status": "ready",
+  "preflight": {
+    "version": 1,
+    "status": "ready",
+    "checks": []
+  },
+  "artifacts": {
+    "leads-csv": "C:/work/workflow-output/leads.csv",
+    "workflow-summary-json": "C:/work/workflow-output/workflow-summary.json"
+  },
+  "steps": [
+    {
+      "id": "discovery",
+      "state": "will-run",
+      "dependsOn": [],
+      "inputs": ["manual-input-csv"],
+      "outputs": ["leads-csv", "discovery-summary-json", "reports-dir"],
+      "networkAccess": ["website-audits"],
+      "settings": {
+        "provider": "manual-csv",
+        "profile": "dental",
+        "concurrency": 2,
+        "maxCandidates": null,
+        "maxAudits": 10
+      }
+    }
+  ]
+}
+```
+
+The top-level status matches the included preflight status:
+
+- `ready` exits `0`, including when preflight contains warnings;
+- `blocked` exits `1`.
+
+For a readable and valid configuration, the plan is produced even when an operational preflight check is blocked, such as a missing API key or input file. If the configuration cannot be read or validated, `artifacts` is empty and `steps` is empty because no trustworthy execution plan can be derived.
+
+Step identifiers, states, artifact identifiers, network-access values, and JSON property meanings are stable within plan report version `1`. Human-readable readiness messages are not a machine-readable policy interface.
+
+Step settings use an object specific to the step identifier. Discovery has `provider`, `profile`, `concurrency`, `maxCandidates`, and `maxAudits`; shortlist has `top`, `minOpportunityScore`, and `sort`; review has `staleBefore`; packaging has `enabled`; summary has an empty settings object. Optional numeric and date settings use `null` rather than being omitted.
+
+## Terminal Output
+
+Terminal output is the default and presents readiness before execution details:
+
+```text
+Workflow plan: READY
+Config: workflow.json
+Provider: manual-csv
+
+Readiness:
+PASS  Workflow configuration is valid
+PASS  Discovery input is readable
+PASS  Output location is writable
+
+Execution plan:
+1. discovery [WILL RUN]
+   Network: website audits (up to 10)
+   Outputs: leads-csv, discovery-summary-json, reports-dir
+
+2. shortlist [WILL RUN]
+
+3. review [DISABLED]
+   Reason: Review is not configured
+
+4. packaging [DISABLED]
+   Reason: Report packaging is not enabled
+
+5. summary [WILL RUN]
+```
+
+A blocked terminal plan writes the complete report to standard output and the concise `open-local-audit: workflow plan blocked` summary to standard error. JSON mode writes exactly one JSON document to standard output for ready and blocked reports and writes no expected readiness text to standard error.
+
+## Components
+
+- A workflow planner builds the versioned plan from one resolved configuration snapshot.
+- Existing preflight check orchestration is reused against that same snapshot so plan and readiness data cannot disagree because the configuration changed between reads.
+- Terminal and JSON renderers format an existing plan without reading configuration or performing checks.
+- The CLI selects execution, preflight, or plan mode and enforces option compatibility.
+
+The package root exports:
+
+- `runWorkflowPlan(configPath)`;
+- `renderWorkflowPlanTerminal(report, configPath)`;
+- `renderWorkflowPlanJson(report)`;
+- only the public types required to consume the version `1` plan report.
+
+Dependency injection helpers, resolved configuration types, and workflow path internals remain outside the package root API.
+
+## Failure Handling
+
+Expected configuration and filesystem readiness failures use the existing sanitized preflight checks. Operationally blocked plans still include execution details when the configuration is valid. Unexpected programming errors continue to propagate through the existing CLI error policy.
+
+No terminal output, JSON output, or thrown expected-readiness error may include API keys, environment values, Google queries, CSV contents, raw configuration, or filesystem error stacks.
+
+Filesystem readiness is advisory. Normal workflow execution continues to validate and safely replace managed outputs at write time.
+
+## Compatibility
+
+Normal `workflow --config <path>` execution is unchanged. The existing `--check` terminal output, JSON report version `1`, public API, and exit behavior remain unchanged. `--plan` is additive and composes preflight rather than expanding the preflight result contract.
+
+Future additive plan fields may be introduced without changing report version `1`. Removing or changing the meaning of a stable identifier, state, or field requires a new plan report version.
+
+## Acceptance Tests
+
+- Manual CSV and Google Places configurations produce deterministic successful-path plans.
+- Review and packaging appear as `disabled`, `conditional`, or `will-run` steps as defined above.
+- Step dependencies and conditional or disabled reasons follow the plan model.
+- Step dependencies, inputs, outputs, settings, and network declarations match the resolved configuration.
+- Relative artifact paths resolve from the configuration directory.
+- Missing input, API key, or output access blocks readiness while retaining a valid execution plan.
+- Invalid or unreadable configuration produces a blocked report with empty artifacts and steps.
+- Plan generation makes no network calls and creates or modifies no files or directories.
+- Terminal and JSON outputs exclude API keys, Google queries, environment values, and raw config contents.
+- JSON output is exactly one parseable document for ready and blocked plans.
+- `--check` and `--plan` together are rejected; `--format` without either option remains rejected.
+- Existing workflow execution and preflight behavior remain covered by regression tests.
+- The packed npm consumer can import the public plan API and includes this architecture document.
+- The release passes lint, build, tests, dependency audit, package dry run, and fresh consumer installation.

package/docs/architecture/workflow-preflight.md

@@ -0,0 +1,133 @@
+# Workflow Preflight
+
+## Purpose
+
+Workflow preflight validates whether a version `1` workflow configuration is operationally ready without running discovery, calling external APIs, or creating or modifying workflow outputs.
+
+```bash
+open-local-audit workflow --config workflow.json --check
+open-local-audit workflow --config workflow.json --check --format json
+```
+
+The existing `workflow --config <path>` execution behavior remains unchanged. `--format` is accepted with `--check` or `--plan` and remains invalid for normal workflow execution.
+
+## Goals
+
+- Validate the strict workflow configuration before execution.
+- Check local inputs, optional review state, API key availability, output writability, and managed-path safety.
+- Show the stages and managed outputs that a real workflow would use.
+- Produce stable terminal and JSON results for operators and CI jobs.
+- Keep preflight read-only and prevent secrets from appearing in output.
+
+## Non-Goals
+
+Preflight does not:
+
+- call Google Places or any audited website;
+- create output directories or probe writability by creating temporary files;
+- run discovery, shortlist, review, or packaging stages;
+- estimate currency costs or promise external API availability;
+- send outreach, upload reports, or synchronize CRM records.
+
+## Checks
+
+The preflight service performs these checks in order:
+
+1. Read and validate the strict version `1` JSON configuration.
+2. For `manual-csv`, require the discovery input to exist as a readable regular file.
+3. For `google-places`, require the existing Google Maps API key resolver to return a nonblank value without exposing it or making a network request.
+4. When a review CSV is configured, verify it is a readable regular file when present. A missing review CSV is a warning because the workflow may create it.
+5. Find the nearest existing ancestor for `outDir` and verify that it is a directory with write access.
+6. Inspect existing `outDir`, `reports/`, enabled `packages/`, and config-managed output files. Reject linked managed paths and canonical directories that escape `outDir`.
+7. Report the enabled workflow stages, configured limits, and resolved managed output paths.
+
+Filesystem access checks are advisory and can become stale before execution. The workflow retains its existing write-time containment checks as the authoritative enforcement boundary.
+
+## Result Contract
+
+`workflow --plan` includes a preflight result alongside an execution plan; its additive contract is defined in the [workflow plan contract](./workflow-plan.md). The version `1` preflight report remains unchanged.
+
+The preflight report is versioned independently from the workflow configuration:
+
+```json
+{
+  "version": 1,
+  "status": "ready",
+  "checks": [
+    {
+      "id": "configuration",
+      "status": "pass",
+      "message": "Workflow configuration is valid"
+    }
+  ],
+  "stages": ["discovery", "shortlist"],
+  "outputs": {
+    "outDir": "C:/work/workflow-output",
+    "workflowSummaryJson": "C:/work/workflow-output/workflow-summary.json"
+  },
+  "limits": {
+    "maxCandidates": null,
+    "maxAudits": 10
+  }
+}
+```
+
+The report uses:
+
+- `ready` when no check failed; warnings are allowed and the command exits `0`;
+- `blocked` when one or more checks failed; the command exits `1`;
+- `pass`, `warn`, or `fail` for individual checks.
+
+Check identifiers are stable machine-readable strings. Messages are human-readable and must not contain API keys, environment values, or raw configuration contents.
+
+`maxCandidates` is the configured Google Places candidate limit and is `null` for manual CSV. `maxAudits` is the configured audit cap and is `null` when no cap is configured. These values describe limits, not predicted usage or cost.
+
+## Terminal Output
+
+Terminal output is the default and is written to standard output:
+
+```text
+Workflow preflight: READY
+Config: workflow.json
+Provider: manual-csv
+
+PASS  Workflow configuration is valid
+PASS  Discovery input is readable
+PASS  Output location is writable
+WARN  Review CSV does not exist and will be created
+
+Stages: discovery -> shortlist -> review
+Managed output: ./workflow-output
+```
+
+For a blocked terminal preflight, the full report remains on standard output and the CLI writes its existing concise `open-local-audit:` error summary to standard error.
+
+With `--format json`, standard output contains exactly one JSON document for both ready and blocked results. The exit code remains authoritative; no additional human-readable text is written to standard output.
+
+## Components
+
+- `workflow-preflight.ts` owns check orchestration and the versioned result type.
+- Small shared workflow path and output modules own no-write inspection, write-time managed-directory preparation, and same-directory temporary-file replacement for managed outputs.
+- Terminal and JSON renderers convert a preflight result without performing checks.
+- `cli.ts` selects normal execution or preflight while preserving the existing error prefix and exit behavior.
+
+## Failure Handling
+
+Configuration read and validation errors are converted into a blocked preflight report. Independent checks continue where their prerequisites are available so one invocation can report all actionable local problems. Checks that depend on an invalid configuration are omitted rather than reported as additional failures.
+
+Expected operational filesystem errors are sanitized and represented as failed checks; unexpected programming errors still propagate. The command must never include a resolved API key in thrown errors, terminal output, or JSON output.
+
+## Acceptance Tests
+
+- A valid manual CSV configuration is ready, exits `0`, and creates no files or directories.
+- Missing, unreadable, or non-file manual input blocks execution.
+- Google API key presence passes without a network request; a missing key blocks execution.
+- A missing review CSV produces a warning, while an unreadable or non-file review path fails.
+- A missing output tree passes when its nearest existing ancestor is writable.
+- An unwritable output ancestor blocks execution without creating a probe file.
+- Linked or canonically escaping managed directories, and linked managed output files, block execution.
+- Terminal and JSON outputs contain no API key or raw environment value.
+- JSON output is one parseable document for ready and blocked results.
+- `--format` without `--check` or `--plan` is rejected.
+- Existing workflow execution and failure behavior remains covered by regression tests.
+- The release passes the full release check, package audit, and fresh consumer installation check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-local-audit",
-  "version": "0.62.0",
+  "version": "0.64.0",
   "description": "Open-source website and local presence auditor for small businesses.",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,10 @@
     "dist",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/architecture/workflow-command.md",
+    "docs/architecture/workflow-preflight.md",
+    "docs/architecture/workflow-plan.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",