@qobi/seocode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SEOCode
+
+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/dist/src/billing/polar.js

@@ -0,0 +1,127 @@
+/**
+ * Server-side Polar API client — used at activation time to PROVE a person
+ * actually paid before we grant a plan. Never trust a plan/subscription id that
+ * arrives from the browser; always re-fetch it here with the org access token.
+ *
+ * Response shapes are parsed defensively: Polar's fields are accessed with
+ * fallbacks so a minor schema change degrades gracefully rather than throwing.
+ * Confirm the exact field names against a real API response the first time.
+ */
+const DEFAULT_BASE = 'https://api.polar.sh';
+const VALID_PLANS = new Set(['free', 'studio']);
+const ACTIVE_STATUSES = new Set(['active', 'trialing']);
+function base(env) {
+    return (env.POLAR_API_BASE ?? DEFAULT_BASE).replace(/\/$/, '');
+}
+async function polarGet(env, path) {
+    const res = await fetch(`${base(env)}${path}`, {
+        headers: {
+            Authorization: `Bearer ${env.POLAR_API_TOKEN}`,
+            Accept: 'application/json',
+            'User-Agent': 'SEOCode-Activation',
+        },
+    });
+    if (!res.ok) {
+        // Log the failure (status + path only — never the token) so activation
+        // problems are traceable. 404s are expected (unknown id/email); warn on the rest.
+        console.warn(`[WARN] Polar API ${res.status} for ${path}`);
+        return null;
+    }
+    return res.json();
+}
+/** Resolves the internal plan from a Polar product object. */
+export function resolvePlan(product) {
+    const fromMeta = (product?.metadata?.plan ?? '').toString().toLowerCase();
+    if (VALID_PLANS.has(fromMeta))
+        return fromMeta;
+    const fromName = (product?.name ?? '').toString().toLowerCase();
+    for (const p of ['studio']) {
+        if (fromName.includes(p))
+            return p;
+    }
+    return null;
+}
+function normalizeSubscription(sub) {
+    if (!sub)
+        return null;
+    const plan = resolvePlan(sub.product);
+    if (!plan) {
+        // Expected misconfiguration: a paid product without a resolvable plan.
+        // Log it (id only) so it can be traced to the product's metadata.
+        console.warn(`[WARN] Polar subscription ${sub.id ?? '?'} has no resolvable plan — set the product's metadata.plan (pro|team|agency)`);
+        return null;
+    }
+    const status = (sub.status ?? '').toString().toLowerCase();
+    const email = sub.customer?.email ?? sub.customer_email ?? sub.user?.email ?? '';
+    return {
+        plan,
+        subscriptionId: sub.id ?? '',
+        customerEmail: email.toLowerCase(),
+        githubOrgHint: sub.custom_field_data?.github_org,
+        active: ACTIVE_STATUSES.has(status),
+    };
+}
+/**
+ * Resolve a paid subscription from a checkout id (the `{CHECKOUT_ID}` Polar
+ * puts in the success URL). This is the same-session / link-in-receipt path.
+ */
+export async function activationFromCheckout(env, checkoutId) {
+    const checkout = await polarGet(env, `/v1/checkouts/${encodeURIComponent(checkoutId)}`);
+    if (!checkout)
+        return null;
+    // A completed checkout links to a subscription — prefer resolving that directly.
+    const subId = checkout.subscription_id ?? checkout.subscription?.id;
+    if (subId) {
+        const info = await activationFromSubscriptionId(env, subId);
+        if (info)
+            return info;
+    }
+    // The subscription may not be linked to the checkout yet (Polar creates it
+    // slightly async). Fall back to resolving the real subscription by the
+    // checkout's customer email, so we still capture a proper subscription id.
+    const email = (checkout.customer_email ?? checkout.customer?.email ?? '').toLowerCase();
+    if (email) {
+        const byEmail = await activationFromEmails(env, [email]);
+        if (byEmail?.active)
+            return byEmail;
+    }
+    // Last resort: use fields on the checkout itself (subscription id may be blank).
+    const plan = resolvePlan(checkout.product);
+    if (!plan)
+        return null;
+    const status = (checkout.status ?? '').toString().toLowerCase();
+    return {
+        plan,
+        subscriptionId: subId ?? '',
+        customerEmail: email,
+        githubOrgHint: checkout.custom_field_data?.github_org,
+        active: status === 'confirmed' || status === 'succeeded' || status === 'paid',
+    };
+}
+export async function activationFromSubscriptionId(env, subscriptionId) {
+    const sub = await polarGet(env, `/v1/subscriptions/${encodeURIComponent(subscriptionId)}`);
+    return normalizeSubscription(sub);
+}
+/**
+ * Cross-device fallback: the user signs in with GitHub on any device and we
+ * match their verified GitHub email to a Polar customer's active subscription.
+ * Returns the first active paid subscription found across the given emails.
+ */
+export async function activationFromEmails(env, emails) {
+    for (const email of emails) {
+        const customers = await polarGet(env, `/v1/customers/?email=${encodeURIComponent(email)}`);
+        const items = customers?.items ?? customers?.result?.items ?? [];
+        for (const customer of items) {
+            if (!customer?.id)
+                continue;
+            const subs = await polarGet(env, `/v1/subscriptions/?customer_id=${encodeURIComponent(customer.id)}&active=true`);
+            const subItems = subs?.items ?? subs?.result?.items ?? [];
+            for (const sub of subItems) {
+                const info = normalizeSubscription(sub);
+                if (info?.active)
+                    return info;
+            }
+        }
+    }
+    return null;
+}

package/dist/src/billing/repo-limits.js

@@ -0,0 +1,60 @@
+/**
+ * Repository access model (2-tier):
+ *
+ *   Developer (free)  → unlimited PUBLIC repos + 1 PRIVATE repo
+ *   Studio  ($19/mo)  → unlimited public + unlimited private, across unlimited orgs
+ *
+ * Public repositories are always covered on every tier. The only gate is the
+ * number of PRIVATE repositories a Free org may review.
+ */
+export const PLAN_PRIVATE_REPO_LIMITS = {
+    free: 1,
+    studio: Infinity,
+};
+const KEY_PREFIX = 'privrepos:';
+function reposKey(orgLogin) {
+    return `${KEY_PREFIX}${orgLogin.toLowerCase()}`;
+}
+/** Private repos an org has enrolled, in first-seen order. */
+export async function getEnrolledRepos(orgLogin, kv) {
+    const raw = await kv.get(reposKey(orgLogin));
+    return raw ? JSON.parse(raw) : [];
+}
+/**
+ * Decides whether a repo may be reviewed. Public repos are always allowed.
+ * Private repos are enrolled first-come up to the plan's private cap.
+ */
+export async function checkRepoAccess(orgLogin, repo, isPrivate, plan, kv) {
+    const limit = PLAN_PRIVATE_REPO_LIMITS[plan];
+    // Public repositories are covered on every tier — no slot consumed.
+    if (!isPrivate) {
+        return { allowed: true, isPrivate: false, limit, count: 0 };
+    }
+    const enrolled = await getEnrolledRepos(orgLogin, kv);
+    const name = repo.toLowerCase();
+    if (enrolled.includes(name)) {
+        return { allowed: true, isPrivate: true, limit, count: enrolled.length };
+    }
+    if (enrolled.length < limit) {
+        enrolled.push(name);
+        await kv.put(reposKey(orgLogin), JSON.stringify(enrolled));
+        return { allowed: true, isPrivate: true, limit, count: enrolled.length };
+    }
+    return { allowed: false, isPrivate: true, limit, count: enrolled.length };
+}
+/** Frees a private repo's slot (e.g. when the app is removed from it). */
+export async function releaseRepo(orgLogin, repo, kv) {
+    const key = reposKey(orgLogin);
+    const enrolled = await getEnrolledRepos(orgLogin, kv);
+    const next = enrolled.filter(r => r !== repo.toLowerCase());
+    if (next.length === enrolled.length)
+        return;
+    if (next.length === 0)
+        await kv.delete(key);
+    else
+        await kv.put(key, JSON.stringify(next));
+}
+/** Frees every private slot for an org (e.g. when the app is uninstalled). */
+export async function clearRepos(orgLogin, kv) {
+    await kv.delete(reposKey(orgLogin));
+}

package/dist/src/billing/subscription-service.js

@@ -0,0 +1,123 @@
+const KEY_PREFIX = 'sub:';
+/**
+ * Maps the plan name from GitHub Marketplace to the internal Plan type.
+ * Names must match exactly what is configured in the Marketplace listing
+ * (comparison is case-insensitive via .toLowerCase()).
+ */
+const PLAN_NAME_MAP = {
+    'developer': 'free',
+    'free': 'free',
+    'studio': 'studio',
+    'team': 'studio', // in case the Polar product is named "Studio / Team"
+};
+function planKey(orgLogin) {
+    // Always lowercase — prevents duplicate records from GitHub payload case variations
+    return `${KEY_PREFIX}${orgLogin.toLowerCase()}`;
+}
+/**
+ * Returns the organisation's subscription.
+ * Falls back to a free plan if the org has never been seen — e.g. they
+ * installed via the GitHub App directly without going through Marketplace.
+ */
+export async function getSubscription(orgLogin, kv) {
+    const raw = await kv.get(planKey(orgLogin));
+    if (raw)
+        return JSON.parse(raw);
+    return {
+        plan: 'free',
+        installedAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        marketplacePlanId: 0,
+        sender: 'unknown',
+    };
+}
+/**
+ * Creates or updates the subscription for an org based on a marketplace_purchase event.
+ * Idempotent — safe to call multiple times with the same payload (GitHub retries).
+ */
+export async function upsertSubscription(payload, kv) {
+    const orgLogin = payload.marketplace_purchase.account.login;
+    const planName = payload.marketplace_purchase.plan.name.toLowerCase();
+    const plan = PLAN_NAME_MAP[planName] ?? 'free';
+    const raw = await kv.get(planKey(orgLogin));
+    const existing = raw ? JSON.parse(raw) : null;
+    const subscription = {
+        plan,
+        // Preserve original install date on plan changes — only set on first purchase
+        installedAt: existing?.installedAt ?? new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        marketplacePlanId: payload.marketplace_purchase.plan.id,
+        sender: payload.sender.login,
+    };
+    await kv.put(planKey(orgLogin), JSON.stringify(subscription));
+}
+/**
+ * Provider-agnostic activation. Sets an org's plan directly, without a
+ * GitHub Marketplace payload — used by external payment providers (e.g. Polar)
+ * whose checkout captures the target org via a custom field.
+ *
+ * Preserves installedAt on repeat calls, same as upsertSubscription.
+ * marketplacePlanId is 0 for non-Marketplace subscriptions.
+ */
+export async function setPlan(orgLogin, plan, kv, sender = 'unknown') {
+    const raw = await kv.get(planKey(orgLogin));
+    const existing = raw ? JSON.parse(raw) : null;
+    const subscription = {
+        plan,
+        installedAt: existing?.installedAt ?? new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        marketplacePlanId: 0,
+        sender,
+    };
+    await kv.put(planKey(orgLogin), JSON.stringify(subscription));
+}
+/**
+ * Deletes the subscription record when an org cancels.
+ * On the next PR event they will fall back to free plan defaults.
+ * Calling this on a non-existent key is a no-op — safe.
+ */
+export async function deleteSubscription(orgLogin, kv) {
+    await kv.delete(planKey(orgLogin));
+}
+// ── Reverse index: Polar customer email → activated orgs ──────────────────────
+//
+// The activation flow lets a buyer PICK the org after paying, so the Polar
+// subscription may not carry the org name. To revoke or change a plan when a
+// cancellation/downgrade webhook arrives, we look the org(s) up by the customer
+// email — which we always have on both sides.
+const INDEX_PREFIX = 'actidx:';
+function indexKey(email) {
+    return `${INDEX_PREFIX}${email.toLowerCase()}`;
+}
+/** Records that `email` activated `orgLogin` (idempotent). */
+export async function recordActivation(email, orgLogin, kv) {
+    if (!email)
+        return;
+    const raw = await kv.get(indexKey(email));
+    const orgs = raw ? JSON.parse(raw) : [];
+    const org = orgLogin.toLowerCase();
+    if (!orgs.includes(org)) {
+        orgs.push(org);
+        await kv.put(indexKey(email), JSON.stringify(orgs));
+    }
+}
+/** Removes one org from an email's activation index. */
+export async function removeActivation(email, orgLogin, kv) {
+    if (!email)
+        return;
+    const raw = await kv.get(indexKey(email));
+    if (!raw)
+        return;
+    const orgs = JSON.parse(raw).filter(o => o !== orgLogin.toLowerCase());
+    if (orgs.length === 0)
+        await kv.delete(indexKey(email));
+    else
+        await kv.put(indexKey(email), JSON.stringify(orgs));
+}
+/** All orgs a given customer email has activated. */
+export async function findOrgsByEmail(email, kv) {
+    if (!email)
+        return [];
+    const raw = await kv.get(indexKey(email));
+    return raw ? JSON.parse(raw) : [];
+}

package/dist/src/billing/tier.js

@@ -0,0 +1,14 @@
+/**
+ * Rules are UN-GATED: every tier — including Free (Developer) — runs the
+ * complete ruleset. The paid Studio tier is differentiated by unlimited private
+ * repositories, unlimited organizations, and support — never by hiding rules.
+ * (You can't prove value if the free product only catches a handful of issues.)
+ *
+ * Kept as a pass-through so callers don't need to change if gating ever returns.
+ */
+export function filterRulesForPlan(rules, _plan) {
+    return rules;
+}
+export function isPaidPlan(plan) {
+    return plan === 'studio';
+}

package/dist/src/billing/types.js

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

package/dist/src/cli/discover.js

@@ -0,0 +1,62 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { isSupportedFile } from '../parsers/index.js';
+import { isPathExcluded } from '../config/seocode-config.js';
+// Directories a local scan should never descend into.
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '.next', 'dist', 'build', 'out', 'coverage',
+    '.cache', '.turbo', '.vercel', '.svelte-kit', '.astro', '.output',
+]);
+/**
+ * Walks the given paths (files or directories, relative to `root`) and returns
+ * the absolute paths of every SEOCode-reviewable file, minus build/vendor dirs
+ * and anything matched by the repo's `.seocode.json` exclude globs. Deterministic
+ * order so output is stable across runs.
+ */
+export function discoverFiles(root, inputs, excludeGlobs) {
+    const targets = inputs.length ? inputs.map(p => path.resolve(root, p)) : [root];
+    const found = [];
+    const seen = new Set();
+    const maybeAdd = (full) => {
+        if (seen.has(full) || !isSupportedFile(full))
+            return;
+        const rel = path.relative(root, full).split(path.sep).join('/');
+        if (isPathExcluded(rel, excludeGlobs))
+            return;
+        seen.add(full);
+        found.push(full);
+    };
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name))
+                    walk(full);
+            }
+            else if (e.isFile()) {
+                maybeAdd(full);
+            }
+        }
+    };
+    for (const target of targets) {
+        let stat;
+        try {
+            stat = fs.statSync(target);
+        }
+        catch {
+            continue; // path doesn't exist — skip quietly
+        }
+        if (stat.isFile())
+            maybeAdd(target);
+        else if (stat.isDirectory())
+            walk(target);
+    }
+    return found.sort();
+}

package/dist/src/cli/fix.js

@@ -0,0 +1,24 @@
+/**
+ * Applies every provably-correct 1-click fix (issues carrying a `suggestion`) to
+ * a file's content. Suggestions replace an inclusive 1-based line span with new
+ * text; we apply them bottom-up so earlier edits don't shift later line numbers.
+ * Only the safe, deterministic transforms the engine emits (e.g. `loading="lazy"`,
+ * `rel="noopener noreferrer"`) ever carry a suggestion — this never guesses.
+ */
+export function applyFixes(content, issues) {
+    const suggestions = issues
+        .map(i => i.suggestion)
+        .filter((s) => !!s)
+        .sort((a, b) => b.startLine - a.startLine); // bottom-up
+    if (suggestions.length === 0)
+        return { content, applied: 0 };
+    const lines = content.split('\n');
+    let applied = 0;
+    for (const s of suggestions) {
+        if (s.startLine < 1 || s.endLine < s.startLine || s.endLine > lines.length)
+            continue;
+        lines.splice(s.startLine - 1, s.endLine - s.startLine + 1, ...s.replacement.split('\n'));
+        applied++;
+    }
+    return { content: lines.join('\n'), applied };
+}

package/dist/src/cli/format-terminal.js

@@ -0,0 +1,66 @@
+import * as path from 'path';
+const SEV_ORDER = ['critical', 'warning', 'info'];
+/** Minimal ANSI — no dependency. Disabled when `color` is false. */
+function painter(color) {
+    const wrap = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
+    return {
+        bold: wrap('1'), dim: wrap('2'),
+        red: wrap('31'), yellow: wrap('33'), blue: wrap('34'),
+        green: wrap('32'), gray: wrap('90'), cyan: wrap('36'),
+    };
+}
+const SEV_LABEL = { critical: 'error', warning: 'warn', info: 'info' };
+/**
+ * ESLint-style terminal output: findings grouped by file, `line:col`-aligned,
+ * severity-colored, with a one-line summary. Returns the string to print; the
+ * caller decides the exit code from the returned counts.
+ */
+export function formatTerminal(report, opts) {
+    const c = painter(opts.color);
+    const sevColor = {
+        critical: c.red, warning: c.yellow, info: c.blue,
+    };
+    const out = [];
+    if (report.files.length === 0) {
+        out.push('');
+        out.push(`  ${c.green('✔')} No SEO issues found ${c.dim(`(${report.scanned} file${report.scanned === 1 ? '' : 's'} scanned)`)}`);
+        out.push('');
+        return out.join('\n');
+    }
+    for (const fileReport of report.files) {
+        const relPath = path.relative(opts.root, fileReport.file).split(path.sep).join('/');
+        // A path outside cwd renders as ../../… — fall back to the given path instead.
+        const rel = (!relPath || relPath.startsWith('..')) ? fileReport.file : relPath;
+        out.push('');
+        out.push(c.bold(c.cyan(rel)));
+        // Sort issues: criticals first, then by line.
+        const issues = [...fileReport.issues].sort((a, b) => {
+            const sd = SEV_ORDER.indexOf(a.severity) - SEV_ORDER.indexOf(b.severity);
+            return sd !== 0 ? sd : (a.line ?? 0) - (b.line ?? 0);
+        });
+        const loc = (i) => (i.line != null ? `${i.line}` : '–').padStart(4);
+        for (const i of issues) {
+            const sev = i.severity;
+            const badge = sevColor[sev](SEV_LABEL[sev].padEnd(5));
+            out.push(`  ${c.dim(loc(i))}  ${badge}  ${i.ruleName}  ${c.dim(i.ruleId)}`);
+            out.push(`        ${c.dim('→ ' + i.fix)}`);
+        }
+    }
+    // ── Summary ──
+    out.push('');
+    const parts = [];
+    if (report.critical)
+        parts.push(c.red(`${report.critical} error${report.critical === 1 ? '' : 's'}`));
+    if (report.warning)
+        parts.push(c.yellow(`${report.warning} warning${report.warning === 1 ? '' : 's'}`));
+    if (report.info)
+        parts.push(c.blue(`${report.info} info`));
+    const total = report.critical + report.warning + report.info;
+    const mark = report.critical > 0 ? c.red('✖') : c.yellow('▲');
+    out.push(`  ${mark} ${total} problem${total === 1 ? '' : 's'} (${parts.join(', ')})  ${c.dim(`· ${report.scanned} files scanned`)}`);
+    if (report.critical > 0) {
+        out.push(`  ${c.red('✖')} ${c.bold('deploy-blocking issues present')} — this would fail the merge check.`);
+    }
+    out.push('');
+    return out.join('\n');
+}