diff --git a/BETA_TESTING.md b/BETA_TESTING.md index 6021aa0..231ddf8 100644 --- a/BETA_TESTING.md +++ b/BETA_TESTING.md @@ -1,17 +1,16 @@ -# First developer beta testing guide +# PatchWRK Scanner — developer onboarding and optional testing -Preparation for an initial round of **10 consenting external developers**. Nobody -is enrolled or contacted by this document. Participation and feedback are voluntary; -stop or skip a scenario at any time. Do not submit feedback until the founder opens -the round and you choose to participate. No signup, telemetry or automatic upload. +PatchWRK Scanner is available now. No enrollment or PatchWRK account is required +to install or run it. Feedback is voluntary; never send credentials, private source +or sensitive reports. This guide does not contact or enroll anyone. ## What you are testing -PatchWRK Scanner is free, MIT-licensed and experimental. It runs locally with +PatchWRK Scanner is a free API Compatibility Scanner. Its engine is open source under MIT. It runs locally with **offline, read-only static analysis** of JavaScript/TypeScript. Supported SDK identities are Stripe, OpenAI, Anthropic, Shopify and Twilio. Only Stripe/OpenAI have curated compatibility changes: four narrow historical records. There is no -continuous monitoring, automatic repair or available PatchWRK Cloud service. +continuous monitoring, automatic repair or available PatchWRK Pro service. Scanning does not execute target code, install target dependencies or contact API providers. Downloading the archive requires network access; scanning does not. Optional @@ -21,9 +20,17 @@ sandbox against hostile concurrent changes. Read [SECURITY.md](SECURITY.md). ## Install and first scan -Use **Node.js 24** and the published [v0.1.0 experimental prerelease](https://github.com/patchwrk-dev/patchwrk-scanner/releases/tag/v0.1.0). +For supported macOS Apple Silicon hosts, [Install for VS Code](https://marketplace.visualstudio.com/items?itemName=PatchWRK.patchwrk-scanner-local) +is the primary path. Confirm publisher **PatchWRK** and ID **PatchWRK.patchwrk-scanner-local**. +Requires VS Code **1.137.0+** with embedded **Node 24**; other platforms and Cursor +are unverified, and remote/virtual/web workspaces are unsupported. No separate +Node installation, source build or npm installation is needed for a compatible host. +Open an authorized stable project → PatchWRK sidebar → Run Scan → Reports Only. +See the [extension guide](docs/VSCODE_EXTENSION.md) for explicit history setup and comparison. + +For the standalone CLI, use **Node.js 24** and the published [v0.1.0 CLI prerelease](https://github.com/patchwrk-dev/patchwrk-scanner/releases/tag/v0.1.0). The [README download/verification steps](README.md#download-prebuilt-scanner) are the -primary installation route: download the named archive/checksum, verify, extract into +standalone CLI installation route: download the named archive/checksum, verify, extract into a new directory and run with Node. No cloning, npm install, pnpm or compilation is required. macOS/Ubuntu have CLI test coverage; Windows security is unverified. @@ -91,9 +98,9 @@ unsupported pnpm/Yarn/Bun lock resolution, incomplete provider catalogs and boun traversal/analysis. No production-health, comprehensive security or accuracy guarantee. See [README limitations](README.md#known-limitations). -## Optional feedback after the round opens +## Optional sanitized feedback -Use the seven-question [feedback template](FEEDBACK.md#beta-testing-feedback-template). +Optionally use the existing [feedback template](FEEDBACK.md#beta-testing-feedback-template). [Issues](https://github.com/patchwrk-dev/patchwrk-scanner/issues/new/choose) are for reproducible installation/detection/version/compatibility bugs, provider requests and scoped features. Existing [Discussions](https://github.com/patchwrk-dev/patchwrk-scanner/discussions) @@ -106,22 +113,3 @@ relative paths; never provide API keys, credentials, environment dumps, private customer data or raw sensitive reports. Do not name a private repository. Each answer is optional; no names, emails, company or repository access is requested. Security findings go through [SECURITY.md](SECURITY.md), never public Issues/Discussions. - -## Invitation draft — not sent - -> Would you like to try PatchWRK Scanner in our first small developer testing round? -> It's free and open source, an experimental beta for finding supported API SDK -> evidence and reviewing limited historical compatibility guidance. It scans locally, -> offline and read-only, without executing target code, telemetry or uploads; initial -> obtaining the prebuilt archive needs a download and Node 24, with no source build. Test only stable repositories you're -> authorized to inspect, or start with the synthetic demo. There is no continuous -> monitoring or automatic repair. Participation and sanitized feedback are voluntary; -> you can decline, skip questions or stop at any time. Please read the -> [testing guide](https://github.com/patchwrk-dev/patchwrk-scanner/blob/main/BETA_TESTING.md) -> and [security policy](https://github.com/patchwrk-dev/patchwrk-scanner/blob/main/SECURITY.md) -> before deciding. No API keys or private source are requested. - -Before any outreach or collection, the founder must review this invitation, open -the round, obtain consent to participation, assign feedback/security responders and -confirm handling/retention expectations. Do not create a public tester roster or -claim testers/results exist. Do not promise removal of public posts or their copies. diff --git a/README.md b/README.md index 73b10ee..cb43431 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,39 @@ # PatchWRK Scanner +**Free API Compatibility Scanner — available now.** Find third-party API/SDK integration evidence in JavaScript and TypeScript projects. Review evidence-backed historical assessments, visual reports and saved scan differences. -**Free, MIT-licensed experimental beta.** Offline, read-only and manually initiated. +The **Scanner engine is open source under MIT**. Scans are offline, read-only and manually initiated. No account, API credentials, source upload, target code execution or automatic repair. **Get PatchWRK → Run Scan → View Results → Review History → Compare Scans** +## Install for VS Code — recommended + +[**Install for VS Code**](https://marketplace.visualstudio.com/items?itemName=PatchWRK.patchwrk-scanner-local) + +The current public extension is **PatchWRK: API Compatibility Scanner v0.2.5**, +published by **PatchWRK**, extension ID `PatchWRK.patchwrk-scanner-local`. +It uses the normal release channel with no Marketplace Preview designation. +Supported package: **macOS Apple Silicon (`darwin-arm64`)**. Requires VS Code +**1.137.0+** with embedded **Node 24**. Other platforms and Cursor are unverified; +remote, virtual and web workspaces are unsupported. + +Choose Install on the Marketplace page, open an authorized stable local project, +then click the PatchWRK icon → **Run Scan** → **Reports Only** for a first report. +No clone, npm/pnpm, compilation, separate Scanner or separate Node installation is +needed for a compatible extension host. Enable optional history only after reviewing +and confirming its private directory outside all open projects. Two saved scans are +needed to compare; reports-only scans are not saved retroactively. + +[Extension guide and privacy limits](docs/VSCODE_EXTENSION.md). +This repository publishes the Scanner engine; a public source location for the +VS Code extension adapter has not been verified. MIT licensing alone does not +establish that all extension source is publicly hosted. +The verified standalone CLI remains available below; its version is independent of +the extension version. PatchWRK Pro is an upcoming paid API maintenance platform, not yet available. + ## Download prebuilt Scanner **Requires Node.js 24 (`>=24 <25`)** — the archive includes compiled JavaScript and @@ -17,12 +43,11 @@ below use a macOS/Linux POSIX shell with `curl` and `tar`. [Download Scanner v0.1.0](https://github.com/patchwrk-dev/patchwrk-scanner/releases/download/v0.1.0/patchwrk-scanner-0.1.0.tgz) · [Download checksum](https://github.com/patchwrk-dev/patchwrk-scanner/releases/download/v0.1.0/patchwrk-scanner-0.1.0.tgz.sha256) · -[Experimental prerelease notes](https://github.com/patchwrk-dev/patchwrk-scanner/releases/tag/v0.1.0) +[CLI v0.1.0 prerelease notes](https://github.com/patchwrk-dev/patchwrk-scanner/releases/tag/v0.1.0) Use the named `.tgz` release asset, **not** GitHub's automatic “Source code” archives. No cloning, npm install, pnpm or TypeScript compilation is required. This is a -manual download/extraction workflow, not one-click installation. npm/Marketplace -installation is not offered by this project. +manual download/extraction workflow, not one-click installation. npm installation is not offered. VS Code users can use the Marketplace link above. In a new directory, download both assets (or save them using the links above): @@ -151,7 +176,7 @@ migration recommendation may itself be outdated. ## Security and privacy - Offline, read-only target scanning: no provider calls, source execution, dependency - installation, telemetry or uploads. Network is needed to download the archive only. + installation, telemetry or uploads. Downloads and editor/Marketplace services have their own network behavior. - Use stable checkouts/private output locations. Symlinks/hardlinks and credential paths are excluded; portable path checks are not a hostile-filesystem sandbox. - HTML/history omit absolute target paths, raw arguments and source snippets, but @@ -162,7 +187,7 @@ migration recommendation may itself be outdated. MIT © 2026 Jovan Simon; [LICENSE](LICENSE) and [ownership provenance](PUBLIC_PROVENANCE.md) remain intact. The archive includes third-party licenses/notices. For confidential -vulnerabilities use [SECURITY.md](SECURITY.md), not public issues. Best-effort beta +vulnerabilities use [SECURITY.md](SECURITY.md), not public issues. Best-effort support, no SLA. [Issues](https://github.com/patchwrk-dev/patchwrk-scanner/issues/new/choose), [questions](https://github.com/patchwrk-dev/patchwrk-scanner/discussions) and [sanitized feedback](FEEDBACK.md) use existing GitHub channels; no automatic collection. @@ -176,22 +201,15 @@ entries establish recorded resolution; pnpm/Yarn/Bun locks remain unsupported. Traversal/AST budgets may yield partial results and are not hard parser CPU/heap isolation. Empty or unknown results are not compatibility passes. Read the [detailed discovery/assessment limits](docs/SCANNER_REPORTS.md#detection-and-compatibility-limits) -and [beta testing guide](BETA_TESTING.md). +and [developer onboarding guide](BETA_TESTING.md). Free Scanner offers manual discovery, historical assessments, terminal/JSON/HTML, -opt-in local history and manual comparison. **PatchWRK Cloud is planned and unavailable.** +opt-in local history and manual comparison. **PatchWRK Pro is an upcoming paid API maintenance platform, not yet available.** +Official provider monitoring, impact analysis, AI-assisted repairs, scoped testing and +developer-approved pull requests are planned. There is no continuous monitoring, automatic provider-change intelligence, AI repair, automated migration verification, automatic GitHub PRs or Cloud-hosted dashboards. -## VS Code extension — upcoming, not publicly available - -Planned public installation experience: search **PatchWRK Scanner** in VS Code -Extensions → Install → open a project → click the PatchWRK icon → Run Scan → review -reports, history and comparisons. This is **not a current installation method**. -Use the verified GitHub archive above until an extension is published and verified. -No Marketplace badge or install link is provided. [Required genuine screenshot assets](docs/SCANNER_REPORTS.md#screenshot-assets--pending-approval) -are documented; no approved captures are available in this update. - ## Build from reviewed public source **Contributors only; not required to use the prebuilt Scanner.** Install Git, @@ -210,4 +228,4 @@ node dist/index.js --help Source setup may download build dependencies. Do not run these commands in the scan target or enable lifecycle scripts indiscriminately. The ordinary npm dry-run package is not the self-contained GitHub bundle. Package privacy, license, security -and experimental limitations remain unchanged. See [CONTRIBUTING.md](CONTRIBUTING.md). +and technical limitations remain unchanged. See [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/SECURITY.md b/SECURITY.md index 7e15801..39700ca 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,6 @@ -# Security policy — PatchWRK Scanner experimental beta +# Security policy — PatchWRK Scanner -Current v0.x experimental versions have best-effort support only. No guaranteed +Current Scanner releases have best-effort support only. No guaranteed backports, response times or remediation dates. No third-party audit/certification or production compatibility guarantee is claimed. diff --git a/docs/VSCODE_EXTENSION.md b/docs/VSCODE_EXTENSION.md new file mode 100644 index 0000000..1ee9673 --- /dev/null +++ b/docs/VSCODE_EXTENSION.md @@ -0,0 +1,142 @@ +# VS Code extension — PatchWRK Scanner + +Free API Compatibility Scanner for supported third-party API integrations and evidence-backed compatibility reports. +The Scanner engine is open source under MIT. + +Inspect supported integration evidence, review historical +compatibility findings and keep manual scan results locally. No PatchWRK +account, API credentials, separate Scanner installation or source compilation needed. + +Available publicly in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=PatchWRK.patchwrk-scanner-local) +as **PatchWRK: API Compatibility Scanner**, published by **PatchWRK** +(extension ID `PatchWRK.patchwrk-scanner-local`). Available for **macOS Apple Silicon (`darwin-arm64`)** +on the normal release channel. Current public version: **0.2.5**, with no Marketplace Preview designation. + +## What you can do + +- Start a genuine manual scan with **Run Scan** in the PatchWRK sidebar. +- Discover supported Stripe, OpenAI, Anthropic, Shopify and Twilio SDK evidence. +- Review evidence-backed assessments from a small offline catalog: four historical + Stripe/OpenAI records, not comprehensive or continuously updated API coverage. +- Open **Visual HTML Reports** with source references, uncertainty and expandable evidence. +- Explicitly enable **Local Scan History**, then save and reopen privacy-filtered snapshots. +- **Compare Scans** to review recorded differences without rescanning or editing snapshots. + +There is no overall health score. Unknown or absent findings do not establish +compatibility; an affected finding is not production runtime verification. + +## Install and run + +Verified configuration: **VS Code 1.137.0 on macOS arm64**, with its embedded +**Node.js 24** extension host. The manifest minimum is 1.137.0; a compatible Node 24 +host is also required. Other editor versions, operating systems and Cursor have not +been certified. Remote, virtual and web workspaces are unsupported. + +1. Open [Install for VS Code](https://marketplace.visualstudio.com/items?itemName=PatchWRK.patchwrk-scanner-local) + and choose **Install**, or find the exact extension ID in VS Code Extensions. + Confirm publisher **PatchWRK**. No clone, npm/pnpm installation or build step. + For a separately supplied, reviewed VSIX, use Extensions → … → **Install from VSIX**. +2. Open a stable, authorized local JavaScript/TypeScript project. Trust only a project + you are authorized to inspect. Click the official PatchWRK **P** in the Activity Bar. +3. Click **Run Scan**. Choose **Reports Only** for the simplest first scan, or explicitly + enable local history. Find an unanswered choice in VS Code's notification bell. +4. Review the real report and its limitations. **Latest Report** reopens it without rescanning. + +Scans run only when explicitly requested. No source/configuration code is executed, +target dependencies installed, source uploaded, provider requests made, or telemetry +collected by PatchWRK. Editor/Marketplace services have their own network behavior. + +## History and comparison + +Enabling history requires selecting an existing parent **outside all open projects** +and confirming the exact new private directory. Only then is a project UUID created. +Both directory and project UUID are supplied to the existing Scanner. A reports-only +scan is not saved retroactively. No implicit home storage or Cloud synchronization. + +Run two explicitly saved scans, then open **Scan History** or a recent record to +reopen saved evidence. Compare Scans asks for two records, orders them by validated +original UTC timestamps, and passes older → newer to Scanner. Equal timestamps use +ascending UUID order, disclosed in title/status; invalid metadata refuses comparison. +Time order does not prove source lineage, an improvement or a repair. Records are immutable. + +The approved directory/project association persists in local editor state across +restarts. Reopening the sidebar may read opted-in saved records; it does not start +a scan or silently initialize replacement storage. Missing/invalid retained storage +is refused. This is not a new cross-window coordination or crash-safety guarantee. +New scan reports use Free Scanner branding. Existing saved HTML and recorded notices +can retain historical wording; reopening does not rewrite original snapshots. +Different Scanner/build/catalog fingerprints or partial coverage can make comparison +inconclusive; fewer findings do not prove a repair. + +Choose **Configure Local History** for guided setup. It explains optional local +snapshots and opens VS Code’s native folder picker. Select an existing parent +folder, or create one in the picker where your operating system supports it. +The final confirmation shows both the chosen parent and the dedicated new history +subfolder where future successful scans will be saved. Choose **Create History** +only after reviewing that exact path; Cancel leaves the association unchanged. +You never create snapshot files manually. No Cloud account or source upload. + +Configure Local History also lets you **Disable History** without deleting saved +snapshots or forgetting the approved location. Reports Only scans then save no new +snapshots; existing History and Compare remain available. To resume saving, choose +**Enable History** and confirm the retained directory. It must still be accessible, +private and associated with the original project; missing storage is not recreated. +Native picker new-folder controls vary by platform; no custom folder-creation UI +or automatic scan is added. Interrupted initialization can leave a directory; inspect +it rather than automatically retrying or moving storage. + +Delete Snapshot previews the selected record and requires explicit modal confirmation. +No automatic deletion, retention scheduler or secure-erasure claim. + +## Privacy and safety + +Target scanning is offline and read-only. HTML omits absolute target/output paths, +raw arguments and source snippets. Filenames, identifiers, timestamps and approved +metadata can still be sensitive: review reports and snapshots privately before sharing. +See [Privacy and safety](#privacy-and-safety), [Support](#support) and the [Scanner security policy](https://github.com/patchwrk-dev/patchwrk-scanner/blob/main/SECURITY.md). + +Reports open in script-disabled panels with restrictive CSP and an extension-only +contrast correction for readable dark text on branded light surfaces. Saved HTML +and findings stay unchanged. The sidebar uses only a small local, nonce-authorized +script with restricted messages; no external fonts/assets or network bridge. + +Cancel operation safely abandons pending choices or terminates the active worker. +An old editor notification may remain visible: dismiss it; late answers cannot start +work. Cancellation may leave a completed/incomplete report, snapshot or lock. Inspect +storage before manually retrying. No automatic retry, overwrite or lock cleanup. + +Portable filesystem checks require stable checkouts and do not sandbox hostile +concurrent mutation. Parser budgets are not hard CPU isolation. Local snapshots are +validated, not authenticated. Full independent screen-reader and runtime network +observation are not certified. Support is best effort with no SLA. + +## Scanner and Pro boundaries + +These are free local Scanner capabilities. PatchWRK Pro is an upcoming paid API maintenance platform and is not yet available. Its intended +workflow is Monitor → Detect → Analyze → Repair → Test → Approve; none of those +planned maintenance services is activated by this extension. +This extension does not add automatic API monitoring, proactive alerts, advanced +Impact Intelligence, AI repairs, automatic migrations, automated verification, developer-approved repair pull requests, hosted history, authentication or billing. + +[Bundled Scanner source](https://github.com/patchwrk-dev/patchwrk-scanner) · +[Scanner CLI — GitHub Releases](https://github.com/patchwrk-dev/patchwrk-scanner/releases/tag/v0.1.0) · +[Issues](https://github.com/patchwrk-dev/patchwrk-scanner/issues) · +[Questions](https://github.com/patchwrk-dev/patchwrk-scanner/discussions) + +The public repository contains the Scanner engine. A public source location for +the VS Code extension adapter has not been verified; do not infer complete +extension source availability from the engine link or MIT licensing. + +The extension includes reviewed report-presentation inputs beyond the standalone +CLI v0.1.0 source/archive baseline. Bundled PUBLIC_PROVENANCE identifies those +inputs; no single public source commit containing every current adapter/reporting +input is claimed. Extension and CLI versions and release channels are independent. + +## Support + +Report sanitized bugs through [GitHub Issues](https://github.com/patchwrk-dev/patchwrk-scanner/issues/new/choose), ask questions in [Discussions](https://github.com/patchwrk-dev/patchwrk-scanner/discussions), and report vulnerabilities through the [private security process](https://github.com/patchwrk-dev/patchwrk-scanner/security/advisories/new) or security@patchwrk.dev. Never post credentials, private source or raw sensitive reports. Best effort, no SLA. + +MIT © 2026 Jovan Simon. See the [MIT license](https://github.com/patchwrk-dev/patchwrk-scanner/blob/main/LICENSE), included third-party notices +and bundled library licenses. The bundled Scanner includes the reviewed reporting refinements described in the +included CHANGELOG.md; the separately published CLI v0.1.0 archive remains a distinct +distribution. Extension and CLI version numbers are independent.