npm - @rankture/cli - Versions diffs - 0.1.0 - Mend

@rankture/cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Rankture
+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.

package/README.md ADDED Viewed

@@ -0,0 +1,637 @@
+# @rankture/cli
+> SEO audit tool for developers — check your sites before deploy
+A fast, offline-first SEO checker that runs on your local files. Supports 15+ file types including HTML, JSX/TSX, Vue, Svelte, Astro, Markdown, and template engines. Perfect for CI/CD pipelines, pre-commit hooks, or manual checks before deployment.
+## Supported File Types
+| Type | Extensions | Metadata Extraction |
+|------|------------|---------------------|
+| **HTML** | `.html`, `.htm` | Full SEO checks including viewport, canonical |
+| **Astro** | `.astro` | Frontmatter `title`, `description`; `<Image>` component |
+| **React/Next.js** | `.jsx`, `.tsx` | `export const metadata`, `<Head>`, `<Image>`, `<Link>` |
+| **Vue/Nuxt** | `.vue` | `useSeoMeta()`, `useHead()`, `definePageMeta()`, `<NuxtImg>`, `<NuxtLink>` |
+| **Svelte/SvelteKit** | `.svelte` | `<svelte:head>`, Svelte syntax stripped |
+| **Markdown** | `.md`, `.mdx` | Frontmatter, heading/image/link conversion |
+| **Nunjucks** | `.njk` | Block tags stripped, variables marked as dynamic |
+| **EJS** | `.ejs` | Scriptlets stripped, expressions marked as dynamic |
+| **Handlebars** | `.hbs` | Block helpers stripped, expressions marked as dynamic |
+| **Pug** | `.pug` | Basic tag extraction (h1-h6, img, a, title, meta) |
+| **Liquid** | `.liquid` | Shopify/11ty support, schema blocks stripped |
+## Installation
+```bash
+# Global install
+npm install -g @rankture/cli
+# Or use with npx (no install)
+npx @rankture/cli check ./dist
+# Or add to your project
+npm install --save-dev @rankture/cli
+```
+## Quick Start
+```bash
+# Check your built site (HTML output)
+rankture check ./dist
+# Check source files directly
+rankture check ./src/pages
+rankture check ./src/content
+# Check with JSON output
+rankture check ./dist --format json
+# Fail build on critical issues
+rankture check ./dist --fail-on critical
+# Write report to file
+rankture check ./dist --format json --output seo-report.json
+```
+## Commands
+### `check <path>`
+Run SEO checks on local files.
+```bash
+rankture check ./dist              # Built HTML
+rankture check ./src/pages         # Astro/Next.js pages
+rankture check ./src/content       # Markdown content
+rankture check ./index.html        # Single file
+rankture check ./pages/index.vue   # Vue component
+rankture check ./dist --watch      # Watch mode - re-run on changes
+rankture check ./src --changed     # Only check git changed files
+rankture check ./src --staged      # Only check git staged files (pre-commit)
+```
+**Options:**
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-f, --format <format>` | Output format: `terminal`, `json`, `html` | `terminal` |
+| `-o, --output <file>` | Write output to file | stdout |
+| `--fail-on <level>` | Exit code 1 on: `none`, `critical`, `warning`, `any` | `none` |
+| `--ignore <patterns...>` | Glob patterns to ignore | `[]` |
+| `--config <file>` | Config file path | - |
+| `-w, --watch` | Watch for file changes and re-run checks | `false` |
+| `--changed` | Only check files changed in git (staged + unstaged) | `false` |
+| `--staged` | Only check git staged files (for pre-commit hooks) | `false` |
+**Output Formats:**
+```bash
+# Terminal output (default) - colorful, human-readable
+rankture check ./dist
+# JSON output - for programmatic processing
+rankture check ./dist -f json -o seo-report.json
+# HTML output - visual report to open in browser
+rankture check ./dist -f html -o seo-report.html
+```
+### `init`
+Create a `rankture.config.json` configuration file.
+```bash
+rankture init          # Create config file
+rankture init --force  # Overwrite existing config
+```
+### `validate <type> <file>`
+Validate SEO assets like sitemaps, robots.txt, or schema.
+```bash
+rankture validate sitemap ./public/sitemap.xml
+rankture validate robots ./public/robots.txt
+rankture validate schema ./schema.json  # Coming soon
+```
+**Robots.txt Validation:**
+- User-agent directive presence
+- Sitemap directive presence
+- Valid directive syntax
+- Disallow/Allow path format
+- Crawl-delay values
+- Common mistakes (blocking all, blocking important paths)
+**Sitemap.xml Validation:**
+- Valid XML structure
+- Required `<loc>` tags for all URLs
+- Valid URL formats
+- Optional tag validation (`<lastmod>`, `<changefreq>`, `<priority>`)
+- File size warnings (Google limit: 50MB, 50,000 URLs)
+- URL accessibility sampling
+### `audit <url>` (Coming Soon)
+Audit a live URL with optional Pro features.
+```bash
+rankture audit https://example.com
+rankture audit https://example.com --api-key YOUR_KEY --sync
+```
+## Checks Performed
+The CLI runs **21 offline checks** across 5 categories:
+### Technical SEO (HTML only)
+- ✓ Viewport meta tag*
+- ✓ Language attribute*
+- ✓ Canonical URL*
+- ✓ Robots meta tag
+*Skipped for source files since these are typically in layouts
+### On-Page SEO (All files)
+- ✓ Title tag (exists, length, uniqueness)
+- ✓ Meta description (exists, length)
+- ✓ Single H1 tag
+- ✓ Heading hierarchy (no skipped levels)
+- ✓ Image alt text
+- ✓ Internal link validity
+### Structured Data (HTML only)
+- ✓ JSON-LD presence
+- ✓ Schema.org validation
+- ✓ Speakable schema (voice/AI assistant optimization)
+- ✓ Offer/Product schema (pricing, discounts, availability)
+- ✓ FAQ schema (question/answer structured data)
+- ✓ HowTo schema (step-by-step instructions)
+### Social / Open Graph (HTML only)
+- ✓ og:title, og:description, og:image
+- ✓ og:type, og:url
+- ✓ twitter:card, twitter:title, twitter:description, twitter:image
+### Accessibility (HTML only)
+- ✓ Skip navigation link
+- ✓ Main landmark (`<main>`)
+- ✓ Navigation landmark (`<nav>`)
+- ✓ Buttons with accessible names
+- ✓ Links with accessible names
+- ✓ Form inputs with labels
+- ✓ Positive tabindex anti-pattern
+- ✓ Focus outline removal
+- ✓ Autoplay video with audio
+- ✓ Color contrast (basic check)
+## AI & Voice Optimization
+The CLI includes specialized checks for AI assistants and voice search readiness:
+### Speakable Schema
+Validates that pages have `SpeakableSpecification` schema for voice assistants (Google Assistant, Alexa, Siri):
+```html
+<script type="application/ld+json">
+{
+  "@type": "WebPage",
+  "speakable": {
+    "@type": "SpeakableSpecification",
+    "cssSelector": [".speakable-intro", ".speakable-faq"]
+  }
+}
+</script>
+```
+### Offer/Product Schema
+Validates pricing and product information for rich results:
+```html
+<script type="application/ld+json">
+{
+  "@type": "Product",
+  "offers": {
+    "@type": "Offer",
+    "price": "29.00",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock"
+  }
+}
+</script>
+```
+### FAQ Schema
+Validates FAQ structured data for featured snippets:
+```html
+<script type="application/ld+json">
+{
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is SEO?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "SEO stands for Search Engine Optimization..."
+      }
+    }
+  ]
+}
+</script>
+```
+### HowTo Schema
+Validates step-by-step instructions for rich results:
+```html
+<script type="application/ld+json">
+{
+  "@type": "HowTo",
+  "name": "How to optimize your website",
+  "step": [
+    { "@type": "HowToStep", "text": "Run an SEO audit" },
+    { "@type": "HowToStep", "text": "Fix critical issues" }
+  ]
+}
+</script>
+```
+## Source File Intelligence
+When checking source files (`.astro`, `.tsx`, `.md`, etc.), the CLI:
+### Metadata Extraction
+- **Astro frontmatter** - Reads `title` and `description` from YAML frontmatter
+- **Next.js `metadata`** - Parses `export const metadata: Metadata = { ... }`
+- **Vue composables** - Extracts from `useSeoMeta()`, `useHead()`, `definePageMeta()`
+- **Svelte head** - Reads title and meta from `<svelte:head>` block
+### Component Normalization
+- **Image components** - `<Image>`, `<NuxtImg>`, `<Picture>` → `<img>` for alt text checking
+- **Link components** - `<Link>`, `<NuxtLink>` → `<a>` for internal link checking
+- **JSX curly braces** - Converts `{variable}` to `[dynamic]` markers
+### Template Engines
+- **Nunjucks** - Strips `{% %}` blocks, marks `{{ }}` as dynamic
+- **EJS** - Strips `<% %>` scriptlets, marks `<%= %>` as dynamic
+- **Liquid** - Strips `{% %}` tags and `{% schema %}` blocks
+- **Handlebars** - Strips `{{# }}` helpers, marks `{{ }}` as dynamic
+### Smart Check Handling
+- **Skips layout checks** - Doesn't flag missing viewport/canonical/lang (handled by layouts)
+- **Preserves content checks** - Still validates title, description, headings, images, links
+## Framework-Specific Examples
+### Next.js (App Router)
+```bash
+# Check your pages
+rankture check ./app
+```
+The CLI extracts metadata from:
+```tsx
+// app/page.tsx
+export const metadata: Metadata = {
+  title: 'Home Page',
+  description: 'Welcome to our site',
+};
+```
+### Astro
+```bash
+# Check pages and content
+rankture check ./src/pages ./src/content
+```
+Extracts frontmatter:
+```astro
+---
+title: "Blog Post Title"
+description: "Post description for SEO"
+---
+```
+### Nuxt 3
+```bash
+# Check pages
+rankture check ./pages
+```
+Extracts from composables:
+```vue
+<script setup>
+useSeoMeta({
+  title: 'Page Title',
+  description: 'Page description',
+});
+</script>
+```
+### SvelteKit
+```bash
+# Check routes
+rankture check ./src/routes
+```
+Extracts from `<svelte:head>`:
+```svelte
+<svelte:head>
+  <title>Page Title</title>
+  <meta name="description" content="Description" />
+</svelte:head>
+```
+### Markdown/MDX (Content Collections)
+```bash
+# Check content directory
+rankture check ./content ./src/content
+```
+Extracts frontmatter and converts syntax:
+```md
+---
+title: "Article Title"
+description: "Article description"
+---
+# Main Heading
+![Alt text](./image.jpg)
+[Link text](/page)
+```
+## CI/CD Integration
+### GitHub Actions
+```yaml
+name: SEO Check
+on: [push, pull_request]
+jobs:
+  seo:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Build site
+        run: npm run build
+      - name: Run SEO checks
+        run: npx @rankture/cli check ./dist --fail-on critical
+```
+### GitLab CI
+```yaml
+seo_check:
+  stage: test
+  script:
+    - npm run build
+    - npx @rankture/cli check ./dist --fail-on critical
+```
+### Pre-commit Hook
+```bash
+# package.json
+{
+  "scripts": {
+    "seo:check": "rankture check ./dist --fail-on warning"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npm run build && npm run seo:check"
+    }
+  }
+}
+```
+## Programmatic API
+Use the CLI as a library in your Node.js projects:
+```typescript
+import { checkPage, checkPages } from '@rankture/cli';
+// Check a single page
+const html = '<html>...</html>';
+const report = await checkPage(html, 'https://example.com');
+console.log(report.summary.score); // 85
+console.log(report.summary.critical); // 0
+console.log(report.results); // Array of CheckResult
+// Check multiple pages
+const pages = [
+  { html: '<html>...</html>', url: 'https://example.com' },
+  { html: '<html>...</html>', url: 'https://example.com/about' },
+];
+const fullReport = await checkPages(pages);
+console.log(fullReport.summary.totalPages); // 2
+console.log(fullReport.summary.score); // 82 (average)
+```
+### Individual Checks
+```typescript
+import { parseHtml, checkMetaTags, checkHeadings, checkImages } from '@rankture/cli';
+const html = '<html>...</html>';
+const parsed = parseHtml(html, 'https://example.com');
+// Run individual checks
+const metaResults = checkMetaTags(parsed);
+const headingResults = checkHeadings(parsed);
+const imageResults = checkImages(parsed);
+```
+## Configuration
+Create a `rankture.config.json` in your project root:
+```json
+{
+  "ignore": [
+    "**/404.html",
+    "**/500.html",
+    "**/_*.html"
+  ],
+  "checks": {
+    "title-length": { "min": 30, "max": 60 },
+    "meta-description-length": { "min": 120, "max": 160 },
+    "h1-count": { "expected": 1 }
+  },
+  "failOn": "critical"
+}
+```
+## Output Formats
+### Terminal (default)
+```
+🔍 Checking 5 HTML files...
+✓ index.html (18/20 passed)
+  ✗ [critical] Missing meta description
+  ✗ [warning] Image missing alt text: hero.jpg
+✓ about.html (20/20 passed)
+  All checks passed!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 Summary
+   Pages: 5
+   Score: 92/100
+   Passed: 95
+   Failed: 5 (2 critical, 3 warnings)
+```
+### JSON
+```json
+{
+  "summary": {
+    "totalPages": 5,
+    "score": 92,
+    "passed": 95,
+    "failed": 5,
+    "critical": 2,
+    "warnings": 3
+  },
+  "pages": [
+    {
+      "url": "file://./dist/index.html",
+      "results": [...]
+    }
+  ],
+  "timestamp": "2025-01-15T10:30:00Z"
+}
+```
+## CI/CD Integration
+### GitHub Actions
+```yaml
+# .github/workflows/seo-check.yml
+name: SEO Check
+on:
+  pull_request:
+    branches: [main]
+jobs:
+  seo:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for --changed mode
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Build site
+        run: npm run build
+      # Option 1: Check only changed files (fast)
+      - name: SEO Check (changed files)
+        run: npx @rankture/cli check ./dist --changed --fail-on critical
+      # Option 2: Full check on all files
+      - name: SEO Check (full)
+        run: npx @rankture/cli check ./dist --fail-on critical
+```
+### Pre-commit Hook (with Husky)
+```bash
+# .husky/pre-commit
+#!/bin/sh
+npx @rankture/cli check ./src/pages --staged --fail-on critical
+```
+### GitLab CI
+```yaml
+seo-check:
+  stage: test
+  script:
+    - npm run build
+    - npx @rankture/cli check ./dist --fail-on critical
+  only:
+    - merge_requests
+```
+### Generate HTML Report
+```yaml
+# In GitHub Actions
+- name: Generate SEO Report
+  run: npx @rankture/cli check ./dist -f html -o seo-report.html
+- name: Upload Report
+  uses: actions/upload-artifact@v4
+  with:
+    name: seo-report
+    path: seo-report.html
+```
+## Pro Features (API Key Required)
+With a [Rankture Pro](https://rankture.com/pricing/) subscription, unlock:
+- 🌐 **Live URL auditing** - Check live sites, not just static files
+- 📱 **Mobile & desktop** - Separate audits for each viewport
+- 🔗 **Broken link checking** - HTTP validation of all links
+- ⚡ **Core Web Vitals** - LCP, CLS, FID/INP metrics
+- 📊 **Dashboard sync** - Track progress over time
+- 🤖 **AI suggestions** - Intelligent fix recommendations
+- 📄 **PDF reports** - Branded reports for clients
+```bash
+rankture audit https://example.com --api-key YOUR_KEY --sync
+```
+Get your API key at [rankture.com/dashboard/settings](https://rankture.com/dashboard/settings/)
+## Comparison: Free vs Pro
+| Feature | Free CLI | Pro (API Key) |
+|---------|----------|---------------|
+| Offline HTML checks | ✅ | ✅ |
+| JSON/Terminal output | ✅ | ✅ |
+| CI/CD integration | ✅ | ✅ |
+| Live URL auditing | ❌ | ✅ |
+| Mobile/Desktop audits | ❌ | ✅ |
+| Broken link checking | ❌ | ✅ |
+| Core Web Vitals | ❌ | ✅ |
+| Dashboard sync | ❌ | ✅ |
+| AI suggestions | ❌ | ✅ |
+| PDF reports | ❌ | ✅ |
+## Related
+- [Rankture](https://rankture.com) - Full SEO audit SaaS
+- [Free SEO Audit](https://rankture.com/free-seo-audit/) - One-time free audit
+- [Rankture Blog](https://rankture.com/blog/) - SEO tips and guides
+## License
+MIT © [Rankture](https://rankture.com)

package/dist/cli.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+
2	+ export { }