From b03af0d6106b68b6f55ffceaf24b4e5d55c71aca Mon Sep 17 00:00:00 2001 From: PSkinnerTech Date: Wed, 20 May 2026 21:41:02 -0500 Subject: [PATCH] chore: prepare cli 0.3.0 release --- CHANGELOG.md | 6 +++- docs/prd-deterministic-audit-cli.md | 10 +++---- docs/release-checklist.md | 23 +++++++++++++- ...6-05-21-repo-audit-ci-ergonomics-design.md | 28 +++++++++++++++++ examples/golden/known-issues-summary.json | 2 +- package-lock.json | 3 +- package.json | 2 +- packages/cli/LICENSE | 21 +++++++++++++ packages/cli/README.md | 30 +++++++++++++++++++ packages/cli/package.json | 24 ++++++++++++++- packages/cli/src/audit.mjs | 2 +- packages/cli/src/cli.mjs | 2 +- packages/cli/src/repo-audit.mjs | 2 +- .../cli/test/audit-output-schema.test.mjs | 8 ++--- packages/cli/test/audit.test.mjs | 2 +- packages/cli/test/cli.test.mjs | 2 +- packages/cli/test/package.test.mjs | 3 ++ packages/cli/test/report.test.mjs | 4 +-- 18 files changed, 152 insertions(+), 22 deletions(-) create mode 100644 docs/superpowers/specs/2026-05-21-repo-audit-ci-ergonomics-design.md create mode 100644 packages/cli/LICENSE create mode 100644 packages/cli/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index dab7306..7e274af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,8 @@ # Changelog -## Unreleased - 2026-05-18 +## Unreleased + +## 0.3.0 - 2026-05-21 - Added Phase D.2 deterministic rule-depth findings for duplicate content clusters, structured-data visible-content mismatches, and entity clarity gaps. - Added Phase D.1 render parity findings for explicitly rendered audits, including changed title, description, canonical, missing rendered heading/content, and structured-data loss checks. @@ -24,6 +26,8 @@ - Kept Astro framework coverage limited to detection and static-output audits until an explicit integration-generated route artifact is available. - Hardened repo command guardrails so restricted mode blocks local build and preview command execution before spawning, and explicit preview options take precedence over static output so callers can audit live preview servers even when a stale `dist` directory exists. - Polished CLI Markdown reports with repo Markdown golden coverage and aligned the skill report template, README, PRD, and skill guidance around the same priorities, dimensions, developer tasks, repository evidence, imported measurements, evidence gaps, and sources structure. +- Added a root package `private: true` guardrail to prevent accidental root package publishing. +- Added CLI package metadata, package-facing README, and MIT license files to improve packed package readiness. - Expanded the test suite to cover repo detection, static route discovery, repo audit orchestration, preview lifecycle behavior, CLI validation, report/schema compatibility, packaging, and release-gate hardening. ## 0.2.0 - 2026-05-18 diff --git a/docs/prd-deterministic-audit-cli.md b/docs/prd-deterministic-audit-cli.md index 04bff25..98882a6 100644 --- a/docs/prd-deterministic-audit-cli.md +++ b/docs/prd-deterministic-audit-cli.md @@ -3,7 +3,7 @@ Status: Current implementation baseline plus developer repo-audit roadmap Date: 2026-05-18 Repository: openclaw-geo-seo-audit-skill -Current CLI package: openclaw-geo-seo-audit@0.2.0; main includes unreleased repo audit mode +Current CLI package: openclaw-geo-seo-audit@0.3.0 release candidate Primary users: technical SEOs, growth teams, content strategists, frontend engineers, agency auditors, and AI agents running OpenClaw skills ## 1. Summary @@ -19,7 +19,7 @@ The production direction remains a deterministic SEO/GEO readiness auditor. Actu ### Current baseline -As of `openclaw-geo-seo-audit@0.2.0` plus the merged repo-audit branch, the repository contains a working deterministic CLI and OpenClaw skill wrapper. The CLI can audit local HTML, live URLs, URL lists, sitemap-seeded crawls, bounded same-origin crawls, static output repositories, and explicit preview-server repositories. It emits JSON and Markdown, imports supplied ranking/performance evidence, evaluates deterministic page and site rules, includes repo evidence for source-repository audits, and includes restricted-mode guardrails for untrusted targets. +As of the `openclaw-geo-seo-audit@0.3.0` release candidate, the repository contains a working deterministic CLI and OpenClaw skill wrapper. The CLI can audit local HTML, live URLs, URL lists, sitemap-seeded crawls, bounded same-origin crawls, static output repositories, and explicit preview-server repositories. It emits JSON and Markdown, imports supplied ranking/performance evidence, evaluates deterministic page and site rules, includes repo evidence for source-repository audits, and includes restricted-mode guardrails for untrusted targets. The latest completed product target is developer-focused repo audit completion: repository audits now support explicit build commands, route lists, repo config, CI threshold failures, and deterministic source-level findings without overclaiming rankings. @@ -30,7 +30,7 @@ The current repository contains a working deterministic CLI, an OpenClaw skill w Current remaining gaps: - The CLI can audit static output and explicit preview-server repositories with explicit build commands, route-list parity, and repo config files; remaining repo-audit work focuses on broader framework fixture coverage and deeper deterministic source-level findings. -- Release documentation and changelog entries must stay aligned with the implemented `0.2.0` baseline plus unreleased repo-audit work before publishing the next package version. +- Release documentation and changelog entries must stay aligned with the implemented `0.3.0` release candidate before publishing the next package version. - Some rule IDs exist in the taxonomy before full trigger coverage, especially deeper entity clarity, hidden text risk, duplicate content clusters, and structured-data visible-content mismatch. - Ranking and GEO visibility measurement still depends on supplied exports. API-backed Search Console, SERP provider, and AI-answer probes are future integrations. - The product needs developer-optimized repo audit workflows that can safely build or preview common web apps, crawl generated output, connect source-level evidence to rendered output, and produce CI-friendly failure semantics. @@ -321,7 +321,7 @@ Top-level shape: ```json { "schemaVersion": "1.0.0", - "toolVersion": "0.2.0", + "toolVersion": "0.3.0", "run": {}, "site": {}, "pages": [], @@ -915,7 +915,7 @@ Resolved for developer repo audit completion: ## 22. Release Stabilization And v1.5 Readiness Checklist -Before publishing or tagging `0.2.0`: +Before publishing or tagging `0.3.0`: - Verify the PRD, README, skill wrapper, changelog, and release checklist describe the same shipped CLI baseline. - Run `npm ci`, `npm audit --omit=dev`, `npm test`, `npm run validate`, and `npm pack --dry-run --workspace packages/cli`. diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 30c144e..0c5f898 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -10,6 +10,7 @@ Before publishing: - Confirm `CHANGELOG.md` contains the package version being released. - Confirm `README.md` and `skill/geo-seo-audit/SKILL.md` describe readiness versus measured rankings accurately. - Confirm raw source corpus files remain repository assets and are not included in the CLI package dry run. +- Confirm the root `package.json` has `private: true` so accidental root publishes are blocked. ## Verification @@ -21,6 +22,7 @@ npm audit --omit=dev npm test npm run validate npm pack --dry-run --workspace packages/cli +npm pack --dry-run --json ``` For CI gating, run audits with a severity threshold: @@ -40,9 +42,26 @@ The audit command returns exit code `2` when findings meet or exceed the configu ## Publish Dry Run - Confirm `npm pack --dry-run --workspace packages/cli` includes only intended package files. +- Confirm `npm pack --dry-run` at the repository root is not used as a publish target; the root package is private and the publishable package is the CLI workspace. - Confirm optional Playwright support remains optional. - Confirm fixture/golden files remain repository test assets and are not shipped in the CLI package. +## Packed CLI Smoke + +Pack and install the CLI workspace in a temporary project before publishing: + +```bash +tmpdir="$(mktemp -d)" +npm pack --workspace packages/cli --pack-destination "$tmpdir" +mkdir "$tmpdir/install" +cd "$tmpdir/install" +npm init -y +npm install --ignore-scripts "$tmpdir"/openclaw-geo-seo-audit-*.tgz +npx openclaw-geo-seo-audit --version +npx openclaw-geo-seo-audit --help +npx openclaw-geo-seo-audit explain-rule indexability.noindex +``` + ## Post-Merge Verification After merging release-stabilization work to `main`, run: @@ -55,6 +74,7 @@ npm audit --omit=dev npm test npm run validate npm pack --dry-run --workspace packages/cli +npm pack --dry-run --json git status --short --branch ``` @@ -63,7 +83,8 @@ Expected result: - Audit reports `found 0 vulnerabilities`. - Tests pass. - Validation reports `ok: true`. -- Package dry run lists only intended CLI package files. +- CLI package dry run lists only intended CLI package files. +- Root pack dry run is treated as a private-root packaging sanity check, not a publish artifact. - Git status shows a clean `main` branch. ## GitHub Release Workflow diff --git a/docs/superpowers/specs/2026-05-21-repo-audit-ci-ergonomics-design.md b/docs/superpowers/specs/2026-05-21-repo-audit-ci-ergonomics-design.md new file mode 100644 index 0000000..d055ca2 --- /dev/null +++ b/docs/superpowers/specs/2026-05-21-repo-audit-ci-ergonomics-design.md @@ -0,0 +1,28 @@ +# Repo Audit CI Ergonomics And Task Surfaces + +Status: Draft scoping note, not approved implementation spec + +## Goal + +Make repo audits easier to consume in CI and developer workflows without changing the existing JSON schema incompatibly. + +## Candidate Deliverables + +- Compact summary. +- GitHub annotations. +- SARIF and JUnit emitters. +- Normalized issue projection combining page findings and repo source findings. +- Additive task/source mapping fields. +- One additional framework fixture. + +## Constraints And Risks + +- Keep readiness versus measured visibility language honest. +- Do not overfit SARIF or JUnit output to one CI provider. +- Source line numbers are sparse. +- Schema additions must be additive. +- Keep repo source findings separate in normal Markdown reports. + +## Next Step + +Run a full Superpowers brainstorming/spec pass before implementation. diff --git a/examples/golden/known-issues-summary.json b/examples/golden/known-issues-summary.json index a847587..561aba7 100644 --- a/examples/golden/known-issues-summary.json +++ b/examples/golden/known-issues-summary.json @@ -1,6 +1,6 @@ { "schemaVersion": "1.0.0", - "toolVersion": "0.2.0", + "toolVersion": "0.3.0", "run": { "target": "http://fixture.test/", "mode": "full", diff --git a/package-lock.json b/package-lock.json index d4582f6..8ff1be6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -20,7 +20,8 @@ }, "packages/cli": { "name": "openclaw-geo-seo-audit", - "version": "0.2.0", + "version": "0.3.0", + "license": "MIT", "bin": { "openclaw-geo-seo-audit": "src/index.mjs" }, diff --git a/package.json b/package.json index d90d333..dd559e9 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "openclaw-geo-seo-audit-skill", "version": "0.1.0", - "private": false, + "private": true, "type": "module", "workspaces": [ "packages/*" diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE new file mode 100644 index 0000000..971ad1b --- /dev/null +++ b/packages/cli/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Patrick Skinner + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the Software), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 0000000..4781c67 --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,30 @@ +# openclaw-geo-seo-audit + +Deterministic GEO/SEO readiness audits for websites and source repositories. + +The CLI inspects crawlability, indexability, search appearance, structured data, content answerability, entity clarity, optional performance imports, and repository audit evidence. It reports readiness by default. Measured ranking or AI-answer visibility requires supplied Search Console, SERP, or AI-answer evidence; Lighthouse exports can add performance measurements. + +## Install + +```bash +npm install -g openclaw-geo-seo-audit +``` + +Playwright is optional. Install it in projects where rendered page evidence is needed. + +## Usage + +```bash +openclaw-geo-seo-audit --help +openclaw-geo-seo-audit audit https://example.com --mode full --max-pages 25 --out audit.json --markdown audit.md +openclaw-geo-seo-audit audit-repo ./site --static-dir dist --fail-on P1 --out repo-audit.json --markdown repo-audit.md +openclaw-geo-seo-audit explain-rule indexability.noindex +``` + +Use `--security restricted` for untrusted live-site audits or hosted wrappers. Restricted mode applies guarded network and file access limits and disables local command execution. + +## Outputs + +The CLI emits versioned JSON and optional Markdown. Findings include stable rule IDs, severity, evidence paths, implementation-task guidance, and source citations where applicable. + +Readiness scores are not ranking guarantees. Treat scores and findings as deterministic implementation evidence, then combine them with measured visibility data when available. diff --git a/packages/cli/package.json b/packages/cli/package.json index ae9c342..6012a5d 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,13 +1,35 @@ { "name": "openclaw-geo-seo-audit", - "version": "0.2.0", + "version": "0.3.0", + "description": "Deterministic GEO/SEO readiness audit CLI for websites and source repositories.", "private": false, "type": "module", + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/PSkinnerTech/openclaw-geo-seo-audit-skill.git", + "directory": "packages/cli" + }, + "homepage": "https://github.com/PSkinnerTech/openclaw-geo-seo-audit-skill#readme", + "bugs": { + "url": "https://github.com/PSkinnerTech/openclaw-geo-seo-audit-skill/issues" + }, + "keywords": [ + "seo", + "geo", + "generative-engine-optimization", + "audit", + "cli", + "technical-seo", + "repository-audit" + ], "bin": { "openclaw-geo-seo-audit": "./src/index.mjs" }, "files": [ "src", + "README.md", + "LICENSE", "package.json" ], "scripts": { diff --git a/packages/cli/src/audit.mjs b/packages/cli/src/audit.mjs index e226217..b56f6d7 100644 --- a/packages/cli/src/audit.mjs +++ b/packages/cli/src/audit.mjs @@ -10,7 +10,7 @@ import { evaluateSite } from "./site-rule-engine.mjs"; import { collectSnapshot } from "./snapshot.mjs"; import { isHttpUrl } from "./url-utils.mjs"; -const toolVersion = "0.2.0"; +const toolVersion = "0.3.0"; const readSourceMap = () => { const candidates = [ diff --git a/packages/cli/src/cli.mjs b/packages/cli/src/cli.mjs index f56c853..a0eca64 100644 --- a/packages/cli/src/cli.mjs +++ b/packages/cli/src/cli.mjs @@ -8,7 +8,7 @@ import { detectRepo } from "./repo-detect.mjs"; import { getRule } from "./rules.mjs"; import { collectSnapshot } from "./snapshot.mjs"; -const version = "openclaw-geo-seo-audit 0.2.0"; +const version = "openclaw-geo-seo-audit 0.3.0"; const help = `Usage: openclaw-geo-seo-audit [options] diff --git a/packages/cli/src/repo-audit.mjs b/packages/cli/src/repo-audit.mjs index ad01587..ad8b124 100644 --- a/packages/cli/src/repo-audit.mjs +++ b/packages/cli/src/repo-audit.mjs @@ -7,7 +7,7 @@ import { analyzeFrameworkRouteManifests } from "./repo-manifests.mjs"; import { runCommand, startPreview, stopPreview } from "./repo-process.mjs"; import { discoverStaticRoutes } from "./repo-routes.mjs"; -const toolVersion = "0.2.0"; +const toolVersion = "0.3.0"; const relativePath = (repoPath, targetPath) => { if (!targetPath) return null; diff --git a/packages/cli/test/audit-output-schema.test.mjs b/packages/cli/test/audit-output-schema.test.mjs index eaee34e..28e82b2 100644 --- a/packages/cli/test/audit-output-schema.test.mjs +++ b/packages/cli/test/audit-output-schema.test.mjs @@ -5,7 +5,7 @@ import { validateAuditOutput } from "../src/audit-output-schema.mjs"; test("accepts minimal valid audit output", () => { const result = validateAuditOutput({ schemaVersion: "1.0.0", - toolVersion: "0.2.0", + toolVersion: "0.3.0", run: {}, site: {}, pages: [], @@ -28,7 +28,7 @@ test("rejects missing top-level audit output fields", () => { test("rejects findings missing required fields", () => { const result = validateAuditOutput({ schemaVersion: "1.0.0", - toolVersion: "0.2.0", + toolVersion: "0.3.0", run: {}, site: {}, pages: [], @@ -45,7 +45,7 @@ test("rejects findings missing required fields", () => { test("accepts optional repo evidence section", () => { const audit = { schemaVersion: "1.0.0", - toolVersion: "0.2.0", + toolVersion: "0.3.0", run: {}, site: {}, pages: [], @@ -67,7 +67,7 @@ test("accepts optional repo evidence section", () => { test("rejects optional repo evidence section when it is not an object", () => { const result = validateAuditOutput({ schemaVersion: "1.0.0", - toolVersion: "0.2.0", + toolVersion: "0.3.0", run: {}, site: {}, pages: [], diff --git a/packages/cli/test/audit.test.mjs b/packages/cli/test/audit.test.mjs index 211c40e..d437a5b 100644 --- a/packages/cli/test/audit.test.mjs +++ b/packages/cli/test/audit.test.mjs @@ -20,7 +20,7 @@ const withServer = async (handler, fn) => { test("returns minimal versioned audit output for a local HTML target", async () => { const audit = await runAudit({ target: "examples/fixture-site/index.html", crawl: { mode: "single", maxPages: 1, maxDepth: 0 } }); assert.equal(audit.schemaVersion, "1.0.0"); - assert.equal(audit.toolVersion, "0.2.0"); + assert.equal(audit.toolVersion, "0.3.0"); assert.match(audit.run.configHash, /^[a-f0-9]{64}$/); assert.deepEqual(audit.run.crawl, { mode: "single", maxPages: 1, maxDepth: 0 }); assert.equal(audit.pages.length, 1); diff --git a/packages/cli/test/cli.test.mjs b/packages/cli/test/cli.test.mjs index 676d629..f032947 100644 --- a/packages/cli/test/cli.test.mjs +++ b/packages/cli/test/cli.test.mjs @@ -30,7 +30,7 @@ const freePort = async () => test("prints version", async () => { const result = await capture(["--version"]); assert.equal(result.exitCode, 0); - assert.match(result.stdout, /openclaw-geo-seo-audit/); + assert.equal(result.stdout.trim(), "openclaw-geo-seo-audit 0.3.0"); }); test("prints help", async () => { diff --git a/packages/cli/test/package.test.mjs b/packages/cli/test/package.test.mjs index 9299164..75082ed 100644 --- a/packages/cli/test/package.test.mjs +++ b/packages/cli/test/package.test.mjs @@ -17,4 +17,7 @@ test("packed CLI includes the source map used by audit output", async () => { assert.ok(files.includes("src/audit.mjs")); assert.ok(files.includes("src/source-map.json")); + assert.ok(files.includes("README.md")); + assert.ok(files.includes("LICENSE")); + assert.ok(files.includes("package.json")); }); diff --git a/packages/cli/test/report.test.mjs b/packages/cli/test/report.test.mjs index d097a46..5cb8a14 100644 --- a/packages/cli/test/report.test.mjs +++ b/packages/cli/test/report.test.mjs @@ -4,7 +4,7 @@ import { generateMarkdownReport } from "../src/report.mjs"; const polishedAuditFixture = () => ({ schemaVersion: "1.0.0", - toolVersion: "0.2.0", + toolVersion: "0.3.0", run: { target: "https://example.com", startedAt: "2026-05-20T10:00:00.000Z", @@ -180,7 +180,7 @@ test("includes repository evidence when audit repo evidence exists", () => { test("includes repository build evidence when present", () => { const markdown = generateMarkdownReport({ schemaVersion: "1.0.0", - toolVersion: "0.2.0", + toolVersion: "0.3.0", run: { id: "run", startedAt: "now", endedAt: "now", target: "repo", mode: "repo" }, site: { notes: [] }, pages: [],