eco-office-hours

eco, office-hours, and eco-doctor run the same local CLI. It collects bounded evidence from a local project or public website, combines it with an optional owner drill, and writes an unofficial ECOAI Business Pulse bundle. It does not issue a certification, audit, compliance determination, government submission, or lending decision.

The framework and backend are documented in docs/FRAMEWORK.md and docs/BACKEND_ARCHITECTURE.md.

Quick start

Requires Node.js 22 or newer.

npx [email protected]

Choose Quick check or Full review, then enter your website or project folder. No account is required. For a direct check, add --check https://example.com. To keep the eco command installed, run npm install --global [email protected].

Use ↑/↓ to choose and Enter to continue. Escape, Ctrl+C, or Ctrl+D cancels without starting a check. Set ACCESSIBLE=1 for a static command guide; add NO_COLOR=1 for uncolored output. In CI, a dumb terminal, or when either input or output is piped, the launcher prints help instead of opening a menu. The guide lists direct commands instead of opening an interactive menu. The menu is a shortcut: direct commands remain canonical.

What it creates

A completed run writes a matched PDF, JSON, and Markdown bundle to the current directory. The PDF is the readable Business Pulse, JSON is the machine record, and Markdown carries the same module wording plus the complete evidence record.

The command exits with 0 when collection completes with no high-priority action, 1 for a usage or runtime failure, 2 when a completed collection has a high-priority action, and 3 when collection or file delivery is incomplete. These are workflow results, not a grade.

Unofficial means exactly that: ECOAI does not issue a certification, audit opinion, compliance determination, government submission, or lending decision. Review the bundle before sharing it. To update an installed copy safely, run:

npm install --global eco-office-hours@latest

The framework guide explains how evidence becomes guidance. The backend guide documents collection, privacy, file delivery, and release verification.

More ways to run

A separate Browser review (eco --browser) uses Playwright Chromium alongside the deeper source-HTML checks. See the backend guide for the review boundaries.

eco --check https://example.com
eco --check ./my-app
eco --doctor ./my-app
eco update

Without a global install, a direct website check is npx [email protected] --check https://example.com.

--check collects technical evidence without asking owner questions. --doctor adds the owner drill. A website is copied into a temporary directory for inspection and removed after the run. Use --keep-mirror only when you need to inspect that copy. Private, loopback, link-local, multicast, and reserved destinations are blocked unless the explicit --allow-private flag is present.

Other useful flags:

• --no-color produces plain output; NO_COLOR is also honored.
• --no-anim disables terminal motion.
• ECO_NO_CONFIG=1 disables saved state reads and writes.
• ECO_NO_UPDATE=1 disables background update checks.

Report contract

Every snapshot has five stable sections:

1. Business basics
2. Operating continuity
3. Technology health
4. SOC 2 discussion prompts
5. SBDC / SBA Conversation prep

The Evidence summary uses four statuses: observed-signal, owner-reported, needs-evidence, and not-checked. Framework mappings keep the evidence IDs that support them; they never strengthen a weak source into a stronger claim. Collector limits and errors are part of the snapshot, not hidden warnings.

Run states and exit codes are machine-usable:

• exit 0: complete collection with no high-priority action
• exit 1: usage or runtime failure
• exit 2: complete collection with a high-priority action
• exit 3: incomplete collection, including missing requested answers or a collector/output failure

Assessment state is separate from artifact delivery: complete, partial, or failed. A partial or failed delivery returns exit 3 while preserving the assessment and its evidence. A complete delivery preserves the assessment's exit code; complete does not mean the business has passed an assessment.

Each analysis that reaches a reliable snapshot saves three files in the current working directory, with one basename and run ID:

eco-business-pulse-<safe-target>-<timestamp>-<run8>.pdf
eco-business-pulse-<safe-target>-<timestamp>-<run8>.json
eco-business-pulse-<safe-target>-<timestamp>-<run8>.md

The PDF opens with review status, Start here, Your next 3 moves, and Modules reviewed, followed by grouped detail cards. Each card answers four questions: Where, What we found, What to do, and Evidence. Repeated findings share a card only when their module, plain title, disposition, next action, and source match. Trust and Growth appear as related conversations on the supporting cards. Grouping is a view: it does not remove source records or change the assessment.

Business, Continuity, Technology, Trust, and Growth counts remain available in PDF methodology, Markdown Review counts, and JSON. Counts are not scores or grades; related domains reuse evidence and must not be added together. Markdown follows the same module/card wording and ends with a Complete evidence record containing every canonical section, including excluded records and raw statuses. JSON contains all evidence, requested coverage, presentation data, and delivery results; its artifactSchema is 1.2, independently of the package version. pulse.modules, pulse.unreviewedModules, and pulse.reviewStatus are additive; existing sections, domains, moves, and buckets keep their meaning. Legacy 1.0 artifacts remain valid without these presentation fields; the schema requires all three for 1.1 and 1.2. Version 1.2 also requires selected guidance resources on cards and moves, plus an optional-value localHelp field. The shipped JSON Schema describes the machine contract. Help, version, update, serve, and failures before a snapshot do not create files.

Module banners are packaged decorative JPEGs. The CLI makes no artwork network request; missing or corrupt artwork uses a neutral fallback with the same text. The PDF's first-page summary may shorten long text; its details and methodology, plus the complete Markdown/JSON siblings, preserve the wording and evidence.

Existing files are never overwritten. If a format fails, successful siblings remain usable and the terminal identifies the delivery error. Fix output permissions or disk space and run again for a new bundle; incomplete delivery can leave a hidden reservation file protecting the old identity.

The artifacts contain the redacted requested scope. Website credentials, query values, and fragments are not persisted. Folder scans reject symlinks and disclose file/byte caps. Website redirects are revalidated before each request and DNS results are pinned to the connection. An optional same-origin PNG/JPEG website icon is checked under bounded fetch and dimension limits. Rejected or missing icons use initials and do not change the assessment. Icon bytes exist only in memory and the PDF, never the JSON or mirror files. Unsupported business-name scripts use a PDF fallback with a note; JSON and Markdown retain the full name. Review artifacts before choosing to share them: redaction is not a general-purpose sensitive-content detector.

What is collected

Folder checks recognize common Node/React, Python, PHP/WordPress, Ruby, Java, .NET, Go, and Rust signals. The bounded scan records stack age signals, tests/CI/docs, likely committed-secret patterns, operational documentation, and coverage gaps. It is not a full static-analysis or secret-management control.

Website checks inspect up to the configured same-origin page and byte ceilings, record observed HTTPS/redirect/header behavior, and inspect basic contact, mobile, and metadata signals. The mirror is evidence for this run only.

The owner drill covers business basics, continuity, access, backups, ownership, and critical operating flows. SBDC/SBA routing uses official national finders; a state alone is never treated as proof of a specific local office.

Trusted resources

Business Pulse actions include one or two reviewed links from government, standards bodies, official maintainers, or established technical nonprofits. Routing prefers an exact detector, then an exact evidence or owner topic, then the module fallback. The reviewed evidence is separate from outside guidance: resource links never become evidence and never change a finding or priority.

Resources resolve from the packaged catalog without runtime network requests. Business owners receive a dedicated SBA/SBDC local-help section when they request that handoff. General guidance can still point to official assistance resources. JSON archives the selected records by value under artifactSchema 1.2; valid 1.0 and 1.1 artifacts remain supported. Markdown prints visible URLs and PDF detail pages show visible, clickable links; page one stays link-free. Maintainers review sources every 90 or 180 days, and a release-only gate checks freshness plus canonical URL reachability before publication.

Development

npm test
npm run verify:package
npm run verify:pdf
# Preserve every PDF and 144-DPI page render for manual review:
npm run verify:pdf -- --keep-renders /absolute/path/to/new-review-directory
npm run release:check

PDFKit renders reports and Clack provides the guided menu; Noto Sans fonts, their OFL license, and module artwork are bundled. Ajv is development-only and validates JSON contracts in tests. Packed-install verification runs all three aliases without development dependencies and checks PDF, JSON, and Markdown delivery.

PDF release checks require Poppler (pdfinfo, pdftotext, pdftoppm), MuPDF (mutool), and qpdf on PATH. Missing tools fail the gate. The checker tests fixed complete, incomplete, long-content, Unicode/fallback, and no-icon reports, including metadata, tags, extraction, file integrity, and every page at 144 DPI. Use an empty retention directory: existing review files are never overwritten. Review retained pages visually and perform a screen-reader reading-order pass; automated checks alone do not establish semantic accessibility or PDF/UA conformance. release:check also confirms the version is unused and dry-runs publishing. It does not publish the package.