@eightmedia/flightcheck 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# Flightcheck
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pre-launch website audit CLI and library.
+
+Flightcheck crawls a site and checks what is wrong before go-live: missing meta tags,
+accessibility issues, weak security headers, DNS settings, robots.txt and sitemap
+mismatches, exposed secrets, and more. Every run produces:
+
+- crawl data (`*-raw.json`)
+- a structured report (`*-report.json`) — analysis facts + findings
+- a plain-language Markdown report (`*-report.md`) rendered from that JSON
+
+## Install
+
+In a Node.js project (recommended):
+
+```bash
+npm install @eightmedia/flightcheck
+# or: pnpm add @eightmedia/flightcheck
+# or: yarn add @eightmedia/flightcheck
+```
+
+Requires Node.js 22+. The package is ESM-only (`"type": "module"`).
+
+## Use in a Node project
+
+### CLI via npm scripts
+
+Add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "flightcheck": "flightcheck",
+    "flightcheck:analyze": "flightcheck-analyze"
+  }
+}
+```
+
+Then:
+
+```bash
+npm run flightcheck -- https://example.com
+npm run flightcheck:analyze -- ./flightcheck/20260618.1413-example.com-raw.json
+```
+
+Or call the binaries directly after install:
+
+```bash
+npx flightcheck https://example.com
+npx flightcheck-analyze ./flightcheck/20260618.1413-example.com-raw.json
+```
+
+Without adding it to a project:
+
+```bash
+npx @eightmedia/flightcheck https://example.com
+```
+
+### Programmatic API
+
+```js
+import { runChecks } from "@eightmedia/flightcheck";
+
+const { outputs, results } = await runChecks({
+  startUrl: "https://example.com",
+});
+
+const report = outputs.analyze?.report;
+console.log(report?.analysis.pagesAnalyzed, report?.findings.length);
+
+// Write paths (when analyze ran):
+console.log(outputs.analyze?.reportPath);
+console.log(outputs.analyze?.reportJsonPath);
+```
+
+Lower-level entry points:
+
+```js
+import { runCrawlCheck, runAnalyzeCheck } from "@eightmedia/flightcheck";
+import { listChecks } from "@eightmedia/flightcheck/checks";
+```
+
+See [docs/check-api.md](docs/check-api.md) for the modular check API.
+
+## How it works
+
+1. **Crawl & checks** — pages are scanned and modular checks run (SEO, a11y, security,
+   infra, agent readiness).
+2. **Analyze** — issues become a flat `findings[]` list. Each finding has severity,
+   category, scope, and a short title/message. Site facts (stack, DNS, …) live under
+   `analysis`.
+3. **Reports** — `*-report.json` is the source of truth for tools; `*-report.md` is the
+   same data in readable form (grouped by severity for humans).
+
+| Output | Audience | Purpose |
+| --- | --- | --- |
+| `*-raw.json` | Machine | Source data from all checks |
+| `*-report.json` | Machine / tools | `analysis` + flat `findings[]` |
+| `*-report.md` | Human | Plain-language report from the JSON |
+
+See [docs/analyze.md](docs/analyze.md) for the report schema.
+
+## Quick start
+
+```bash
+npm install @eightmedia/flightcheck
+npx flightcheck https://example.com
+```
+
+This writes timestamped files in `./flightcheck/`, for example:
+
+- `./flightcheck/20260618.1413-example.com-raw.json`
+- `./flightcheck/20260618.1413-example.com-report.json`
+- `./flightcheck/20260618.1413-example.com-report.md`
+
+By default this runs all implemented checks: crawl, security headers, DNS, robots.txt,
+sitemap, agent readiness, and analyze. If the start URL is a domain redirect, only
+redirect validation, DNS, and analyze run. Use `--checks crawl` to force a full crawl on
+redirect domains. Use `--checks` for a subset, or `--json-only` for crawl JSON only.
+
+Re-analyze an existing crawl without re-crawling:
+
+```bash
+npx flightcheck-analyze ./flightcheck/20260618.1413-example.com-raw.json
+```
+
+## Documentation
+
+- [What Flightcheck checks](docs/checks.md) — plain-language checklist
+- [Analyze reports](docs/analyze.md) — `*-report.json` / `*-report.md`
+- [Crawler](docs/crawler.md) — crawl CLI and flags
+- [Check API](docs/check-api.md) — modular checks for developers
+- [Stack detection](docs/stack.md)
+- [Agent readiness](docs/agent-ready.md) — llms.txt, markdown negotiation, …
+- [QC checks plan](docs/qc-checks-plan.md) — roadmap
+- [Docs index](docs/index.md) · [Changelog](CHANGELOG.md)
+
+## Development
+
+```bash
+nvm use   # see .nvmrc
+pnpm install
+pnpm test
+pnpm build
+```
+
+## License
+
+Flightcheck is licensed under [GNU GPL v3.0](LICENSE). You may use, modify, and
+distribute it under the GPL terms. Derivative works must also be open source under a
+compatible license — it cannot be incorporated into closed-source products without
+complying with the GPL (typically by open-sourcing the combined work).

package/dist/analyze/fixManifest.d.ts

@@ -0,0 +1,65 @@
+import type { StackProfile } from "./stack.js";
+import type { Tier1ReportData } from "./reportTier1.js";
+import type { ReportRecord } from "./report.js";
+import { defaultManifestPathForInput } from "../crawler/outputPaths.js";
+export declare const FIX_MANIFEST_VERSION: 1;
+export type LocationDiscovery = "search-codebase" | "hosting-panel" | "dns-panel" | "cms-studio" | "manual";
+export type FixSurface = "repo" | "hosting" | "cms" | "dns" | "manual";
+export type ManifestStackEntry = {
+    name: string;
+    categories: string[];
+    confidence: string;
+    scope: string;
+    evidence: string[];
+};
+export type ManifestIssue = {
+    id: string;
+    severity: string;
+    scope: string;
+    count?: number;
+    todo: string;
+    urls?: string[];
+};
+/**
+ * A crawled URL that is not a real fixable page (404/401/error — often emails, phone
+ * numbers, or dynamic-route placeholders crawled as paths). Surfaced for human review
+ * instead of generating "add metadata" todos against pages that do not exist.
+ */
+export type ReviewItem = {
+    url: string;
+    status: number | null;
+    reason: string;
+};
+export type WorkPackage = {
+    id: string;
+    promptId: string;
+    fixSurface: FixSurface;
+    priority: number;
+    scope: string;
+    template?: string;
+    issues: ManifestIssue[];
+    locationDiscovery: LocationDiscovery;
+    searchHints: string[];
+    mcpServers: string[];
+    prTitle: string;
+    autoFixable: boolean;
+};
+export type FixManifest = {
+    version: typeof FIX_MANIFEST_VERSION;
+    generatedAt: string;
+    source: string;
+    reportPath: string;
+    redirectOnly: boolean;
+    stack: ManifestStackEntry[];
+    workPackages: WorkPackage[];
+    /** Non-200 crawled URLs that should be investigated, not auto-fixed. */
+    reviewItems: ReviewItem[];
+};
+export type BuildFixManifestOptions = {
+    redirectOnly?: boolean;
+    reportPath?: string;
+    stackProfile?: StackProfile;
+};
+export declare function buildFixManifest(sourcePath: string, records: ReportRecord[], tier1?: Tier1ReportData, options?: BuildFixManifestOptions): Promise<FixManifest>;
+export { defaultManifestPathForInput };
+//# sourceMappingURL=fixManifest.d.ts.map

package/dist/analyze/fixManifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixManifest.d.ts","sourceRoot":"","sources":["../../src/analyze/fixManifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,2BAA2B,EAA6B,MAAM,2BAA2B,CAAC;AAEnG,eAAO,MAAM,oBAAoB,EAAG,CAAU,CAAC;AAE/C,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,eAAe,GACf,WAAW,GACX,YAAY,GACZ,QAAQ,CAAC;AAEb,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEvE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,OAAO,oBAAoB,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wEAAwE;IACxE,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,CAAC;AAgnBF,MAAM,MAAM,uBAAuB,GAAG;IACpC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,GAAE,eAAoB,EAC3B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,WAAW,CAAC,CAyBtB;AAED,OAAO,EAAE,2BAA2B,EAAE,CAAC"}