Seogenoptima

Seogenoptima is an autonomous SEO optimization toolkit with a Ruby gem core and a Node.js npm wrapper. It is designed for projects that want one CLI to:

• analyze search demand from Yandex Webmaster and Google Search Console;
• normalize and score under-optimized pages;
• export SEO improvement work orders as JSON;
• apply reviewed metadata to a database;
• generate sitemaps and trigger Next.js revalidation;
• notify search engines using the most appropriate mechanism per URL.

The repository is intentionally kept credential-free. Real tokens, database URLs, service-account JSON files, and local profile state belong in local ignored files such as .env and ./.seogenoptima/.

Architecture

seogenoptima/
├─ ruby/                   # Ruby gem core
├─ examples/               # Integration examples, including Next.js App Router
├─ docs/                   # Public usage docs
├─ package.json            # npm wrapper metadata
├─ index.js                # Node launcher
├─ install.js              # Lazy Ruby runtime bootstrap
└─ README.md

Full usage guide

• npm package page / operator quick start: README.md
• extended operator manual: docs/USAGE.md

The old phase-by-phase implementation notes are treated as local planning material and ignored through .gitignore, so the publishable utility stays clean.

Why Ruby + npm?

• Ruby provides a mature ecosystem for CLI, HTTP, YAML, and database access.
• npm makes installation trivial in Node.js projects: npx seogenoptima ...
• The wrapper keeps Node concerns minimal while the SEO core lives in Ruby.

Requirements

• Node.js 18+
• Ruby 2.7+ with gem available in PATH
• For database-backed workflows: PostgreSQL, MySQL, or SQLite

Installation

npm install seogenoptima

The package uses lazy install:

• postinstall only checks prerequisites;
• the first real CLI execution bootstraps the Ruby gem runtime;
• runtime state is cached under ~/.seogenoptima/runtime.json.

Security and publish-readiness rules

Before publishing or sharing the package:

• keep .seogenoptima/ local only;
• keep provider JSON keys and OAuth tokens outside the repository;
• keep database URLs in ignored local config, not in docs or examples;
• use placeholders in examples and onboarding templates;
• verify the release payload with npm pack --dry-run.

Quick start

1. Authorize providers

npx seogenoptima auth:yandex --token YOUR_YANDEX_TOKEN
npx seogenoptima auth:yandex --client-id YOUR_YANDEX_CLIENT_ID --client-secret YOUR_YANDEX_CLIENT_SECRET --redirect-uri https://oauth.yandex.ru/verification_code
npx seogenoptima auth:yandex --verification-code YOUR_YANDEX_CODE
npx seogenoptima auth:yandex --client-id YOUR_YANDEX_CLIENT_ID --client-secret YOUR_YANDEX_CLIENT_SECRET --redirect-uri https://oauth.yandex.ru/verification_code --verification-code YOUR_YANDEX_CODE
npx seogenoptima auth:google --key ./gsc-service-account.json

2. Store base configuration

npx seogenoptima config init --config ./.seogenoptima --base-url https://mysite.com --database-url sqlite://tmp/seogenoptima.sqlite3 --revalidate-secret change-me

# or set the same values manually if you prefer a piecemeal setup
npx seogenoptima config set nextjs_url https://mysite.com --secret change-me
npx seogenoptima config set database sqlite://./tmp/seogenoptima.sqlite3

# run a preflight check before the first live analysis
npx seogenoptima config doctor --config ./.seogenoptima --format json

# optionally verify live provider access and the target host visibility
npx seogenoptima config doctor --config ./.seogenoptima --check-providers --host https://mysite.com --format json

3. Explore connected sites

npx seogenoptima sites list

4. Analyze a host

npx seogenoptima analyze https://mysite.com --start-date 2026-04-01 --end-date 2026-05-01
npx seogenoptima analyze https://mysite.com --start-date 2026-04-01 --end-date 2026-05-01 --format json

analyze now returns warning-aware diagnostics instead of silently collapsing degraded providers into rows: 0.

• analysis_status is ok or warning;
• provider_summary.google / provider_summary.yandex expose status, reason, message, and provider-specific context;
• warnings aggregates non-OK provider states for automation;
• next_steps suggests the next operational action, typically config doctor --check-providers or credential onboarding.

Common reason values include:

• rows_fetched
• no_data
• credentials_missing
• host_not_visible
• no_visible_properties
• no_visible_hosts
• access_denied
• rate_limited
• provider_unavailable
• request_failed
• partial_failure (Yandex multi-endpoint fetch degraded but partially succeeded)

5. Export suggestions as JSON

npx seogenoptima generate suggestions https://mysite.com --output-file ./tmp/suggestions.json

The exported work order now carries forward the analysis envelope, including:

• analysis_status
• warnings[]
• next_steps[]
• row_count
• provider_summary

It also now includes a richer SEO payload per page:

• proposed.title, proposed.description, proposed.h1
• content_brief with intent, section outline, FAQ angles, and CTA guidance
• page_structure with schema hint, suggested H2 blocks, hero guidance, and internal link targets

If upstream providers degrade but actionable opportunities still exist, generate suggestions completes with a warning-aware payload instead of hiding the degradation.

6. Apply reviewed suggestions

npx seogenoptima apply https://mysite.com --input-file ./tmp/suggestions.json --database sqlite://./tmp/seogenoptima.sqlite3

apply now persists not only the reviewed metadata fields, but also the structured content_brief and page_structure payload into seo_metadata, so downstream database and Next.js workflows can consume more than just meta tags.

7. Sync with Next.js

npx seogenoptima nextjs publish https://mysite.com --database sqlite://./tmp/seogenoptima.sqlite3 --output-file ./.seogenoptima/exports/nextjs-manifest.json
npx seogenoptima nextjs sync https://mysite.com --database sqlite://./tmp/seogenoptima.sqlite3
npx seogenoptima sitemap generate https://mysite.com --base-url https://mysite.com --output-file ./public/sitemap.xml

nextjs publish exports a DB-backed manifest that App Router pages, layouts, and generateMetadata() can consume during SSG/SSR/ISR without coupling the app directly to the CLI internals. The manifest contains per-path title, description, h1, keywords, content_brief, and page_structure.

8. Notify search engines

npx seogenoptima index notify https://mysite.com/jobs/backend-engineer --page-type JobPosting
npx seogenoptima index history mysite.com --database sqlite://./tmp/seogenoptima.sqlite3 --limit 20 --format json

9. Run autonomous mode

npx seogenoptima daemon start https://mysite.com --schedule every_12h --database sqlite://./tmp/seogenoptima.sqlite3
npx seogenoptima daemon run-once https://mysite.com --database sqlite://./tmp/seogenoptima.sqlite3 --format json
npx seogenoptima daemon status https://mysite.com --config ./.seogenoptima --database sqlite://./tmp/seogenoptima.sqlite3 --format json
npx seogenoptima daemon retry https://mysite.com --config ./.seogenoptima --database sqlite://./tmp/seogenoptima.sqlite3 --format json
npx seogenoptima daemon resume https://mysite.com --config ./.seogenoptima --database sqlite://./tmp/seogenoptima.sqlite3 --format json

The daemon pipeline is now guarded:

• it still exports a reviewable work order even when analyze warns;
• it skips auto_apply when analysis produces no observations;
• it skips auto_apply when no suggestions were generated;
• it may continue through apply -> notify when partial provider warnings exist but actionable suggestions were still produced.
• concurrent daemon runs for the same profile + host are blocked by a lockfile;
• stale lockfiles are recovered automatically when their owning PID is no longer alive.

daemon run-once is the safest operator entrypoint for local smoke tests, CI checks, and manual production verification because it returns a structured run summary without starting a long-lived scheduler loop.

daemon status reads the current profile state and reports:

• the latest recorded daemon run for a host;
• the current lockfile snapshot (none, active, or stale);
• a notification_audit block correlated to the latest run window when a database URL is available;
• tracked hosts present in state.yml;
• actionable next steps when the last run degraded or no run has been recorded yet;
• for failed runs: failed_step, retryable, resume_hint, and failure-specific recovery hints.

daemon retry is the current pragmatic recovery entrypoint for v1:

• it reads the last recorded failed run from state.yml;
• it is the right recovery entrypoint for analyze and export failures;
• it refuses blocking failures by default when retryable: false;
• it refuses apply and notify failures by default and points the operator to daemon resume;
• it can be forced with --force after the operator fixes the underlying issue;
• it currently reruns the full pipeline rather than doing a granular partial resume.

daemon resume is the first partial-resume entrypoint for v1:

• it supports failed_step=apply by reusing the saved work order and then continuing to notify;
• it supports failed_step=notify by continuing only the remaining notification URLs/providers from the same failed run;
• it reuses the saved runtime state in state.yml instead of rerunning analyze and export;
• it consults notification_logs using the failed run time window so already submitted provider notifications are not repeated during resume;
• it intentionally refuses earlier failures and points the operator back to daemon retry.

Supported commands

• auth:yandex
• auth:google
• sites list
• analyze [host]
• generate suggestions [host]
• apply [host]
• nextjs publish [host]
• nextjs sync [host]
• nextjs generate-sitemap [host]
• sitemap generate [host]
• index notify [url]
• index history [host]
• config init|doctor|set|get|show
• daemon start|run-once|status|retry|resume

Google integration rules

Seogenoptima intentionally follows the documented limits of Google's APIs:

• Google Indexing API is used only for supported page types such as JobPosting and BroadcastEvent.
• URL Inspection API is not used as a mutation mechanism, because it is read-only.
• For ordinary pages, the fallback is sitemap update + Search Console sitemaps.submit.
• Anonymous sitemap ping is not used because it has been deprecated.

Next.js integration

v1 is App Router first.

The repository includes an example in examples/next-app-router/ with:

• app/api/revalidate/route.ts
• app/lib/seogenoptima.ts
• app/sitemap.ts
• app/robots.ts
• .env.local.example
• postbuild usage idea

The new nextjs publish command is the DB-first publishing layer for App Router projects:

• it writes a neutral JSON manifest that can live inside the project or under ./.seogenoptima/exports/;
• the example helper reads that manifest at runtime and exposes getSeogenoptimaPage() plus toNextMetadata();
• nextjs sync remains the on-demand ISR/revalidation step, while nextjs publish covers SSG/SSR-friendly metadata delivery.

Native app/sitemap.ts and app/robots.ts are preferred for modern projects, while static file generation into public/ remains available as a fallback.

There is also a bootstrap-friendly onboarding starter in examples/production-onboarding/ for teams that want a config template pack alongside the CLI-driven config init flow.

Configuration storage

Seogenoptima stores runtime configuration outside the project by default:

• ~/.seogenoptima/config.yml
• ~/.seogenoptima/credentials.yml
• ~/.seogenoptima/database.yml
• ~/.seogenoptima/state.yml (bootstrap metadata and the latest daemon run summaries)

For daemon failures, state.yml now also stores step-aware diagnostics such as the failed pipeline step, retryability hint, completed steps, recovery guidance, and partial notification progress for safe resume at the apply/notify boundary.

notification_logs are now used as both an audit trail and a recovery signal:

• provider-level notify results are persisted incrementally;
• if one provider succeeds and a later provider fails, the successful provider result is still recorded;
• daemon resume reads those rows for the same failed run and skips only the already submitted providers.

daemon status now also uses those logs as an operator report surface:

• it can correlate notification_logs to the latest run via the run's started_at/finished_at window;
• it shows a compact provider/status/strategy summary for the last run when database access is available;
• it points the operator to index history for the full audit trail.

index history is the operator-facing read-side for that audit trail:

• it lists recent notification log rows for a host or a specific URL;
• it supports provider, status, and limit filters;
• it returns raw provider payloads so daemon recovery and manual notify attempts can be correlated without direct SQL access.

Testing

Ruby tests live under ruby/spec/ and use:

• RSpec
• WebMock

Run them with:

npm test

Repository docs

Public operator documentation lives in docs/USAGE.md.

Internal phase-by-phase planning notes may still exist locally in docs/, but they are intentionally ignored via .gitignore so the published utility remains clean and reusable.

Current environment note

If Ruby is missing from your machine, the npm wrapper cannot execute the SEO core yet. It will explain the missing prerequisite on first run instead of failing silently like a haunted toaster.