sugikit 0.0.1 → 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 (72) hide show
  1. package/LICENSE +29 -21
  2. package/README.md +45 -0
  3. package/dist/api/browser.d.ts +5 -0
  4. package/dist/api/browser.js +5 -0
  5. package/dist/api/rules.d.ts +12 -0
  6. package/dist/api/rules.js +14 -0
  7. package/dist/auth.d.ts +156 -0
  8. package/dist/auth.js +547 -0
  9. package/dist/browser.d.ts +25 -0
  10. package/dist/browser.js +120 -0
  11. package/dist/check.d.ts +21 -0
  12. package/dist/check.js +89 -0
  13. package/dist/convert-probe.d.ts +21 -0
  14. package/dist/convert-probe.js +647 -0
  15. package/dist/fetch.d.ts +6 -0
  16. package/dist/fetch.js +22 -0
  17. package/dist/framework.d.ts +2 -0
  18. package/dist/framework.js +17 -0
  19. package/dist/gather.d.ts +48 -0
  20. package/dist/gather.js +211 -0
  21. package/dist/html.d.ts +17 -0
  22. package/dist/html.js +43 -0
  23. package/dist/http.d.ts +36 -0
  24. package/dist/http.js +57 -0
  25. package/dist/index.d.ts +2 -0
  26. package/dist/index.js +331 -0
  27. package/dist/links.d.ts +8 -0
  28. package/dist/links.js +69 -0
  29. package/dist/polish-run.d.ts +115 -0
  30. package/dist/polish-run.js +357 -0
  31. package/dist/probe.d.ts +14 -0
  32. package/dist/probe.js +457 -0
  33. package/dist/psi-scores.d.ts +4 -0
  34. package/dist/psi-scores.js +7 -0
  35. package/dist/psi.d.ts +56 -0
  36. package/dist/psi.js +192 -0
  37. package/dist/release.d.ts +1 -0
  38. package/dist/release.js +5 -0
  39. package/dist/render.d.ts +28 -0
  40. package/dist/render.js +270 -0
  41. package/dist/report.d.ts +227 -0
  42. package/dist/report.js +69 -0
  43. package/dist/rules/convert-render.d.ts +100 -0
  44. package/dist/rules/convert-render.js +279 -0
  45. package/dist/rules/convert.d.ts +15 -0
  46. package/dist/rules/convert.js +322 -0
  47. package/dist/rules/fixes.d.ts +16 -0
  48. package/dist/rules/fixes.js +536 -0
  49. package/dist/rules/geo.d.ts +15 -0
  50. package/dist/rules/geo.js +112 -0
  51. package/dist/rules/polish.d.ts +59 -0
  52. package/dist/rules/polish.js +223 -0
  53. package/dist/rules/robots.d.ts +14 -0
  54. package/dist/rules/robots.js +69 -0
  55. package/dist/rules/seo.d.ts +31 -0
  56. package/dist/rules/seo.js +208 -0
  57. package/dist/rules/types.d.ts +55 -0
  58. package/dist/rules/types.js +78 -0
  59. package/dist/score.d.ts +6 -0
  60. package/dist/score.js +23 -0
  61. package/dist/skills.d.ts +9 -0
  62. package/dist/skills.js +22 -0
  63. package/package.json +64 -4
  64. package/skills/INSTALL_PROMPT.md +9 -0
  65. package/skills/sugikit/SKILL.md +147 -0
  66. package/skills/sugikit/references/convert.md +127 -0
  67. package/skills/sugikit/references/geo.md +97 -0
  68. package/skills/sugikit/references/next.md +254 -0
  69. package/skills/sugikit/references/pagespeed.md +94 -0
  70. package/skills/sugikit/references/polish.md +123 -0
  71. package/skills/sugikit/references/seo.md +150 -0
  72. package/skills/sugikit/references/tanstack-start.md +246 -0
@@ -0,0 +1,208 @@
1
+ import { load } from "cheerio";
2
+ import { parseRobots } from "./robots.js";
3
+ import { htmlFallbackMessage, isAbsoluteHttpUrl, isHtmlPage, jsonLdBlocks, jsonLdTypes, metaContent, notApplicable, result, textStatusMessage, validText, } from "./types.js";
4
+ export const JSON_LD_TYPES = ["Organization", "SoftwareApplication", "Product", "WebSite", "MobileApplication"];
5
+ function lengthRule(id, label, value, min, max) {
6
+ if (value === undefined)
7
+ return result(id, "warn", false, `${label} is missing, so its length cannot be checked`);
8
+ const ok = value.length >= min && value.length <= max;
9
+ return result(id, "warn", ok, ok
10
+ ? `${label} length is ${value.length} characters`
11
+ : `${label} is ${value.length} characters, aim for ${min} to ${max}`, { evidence: value });
12
+ }
13
+ function title({ $ }) {
14
+ return $("head > title").first().text().trim() || undefined;
15
+ }
16
+ export const seoTitle = (ctx) => {
17
+ const value = title(ctx);
18
+ return result("seo/title", "error", value !== undefined, value ? "Page has a title" : "Page has no <title>", {
19
+ selector: "head > title",
20
+ ...(value ? { evidence: value } : {}),
21
+ });
22
+ };
23
+ export const seoTitleLength = (ctx) => lengthRule("seo/title-length", "Title", title(ctx), 30, 60);
24
+ export const seoMetaDescription = ({ $ }) => {
25
+ const value = metaContent($, "description");
26
+ return result("seo/meta-description", "error", value !== undefined, value ? "Page has a meta description" : 'Page has no <meta name="description">', { selector: 'meta[name="description"]', ...(value ? { evidence: value } : {}) });
27
+ };
28
+ export const seoMetaDescriptionLength = ({ $ }) => lengthRule("seo/meta-description-length", "Meta description", metaContent($, "description"), 70, 160);
29
+ export const seoHtmlLang = ({ $ }) => {
30
+ const lang = $("html").attr("lang")?.trim();
31
+ return result("seo/html-lang", "error", Boolean(lang), lang ? `<html lang="${lang}">` : "<html> has no lang attribute", {
32
+ selector: "html",
33
+ });
34
+ };
35
+ export const seoViewport = ({ $ }) => {
36
+ const value = metaContent($, "viewport");
37
+ return result("seo/viewport", "error", value !== undefined, value ? "Page has a viewport meta tag" : 'Page has no <meta name="viewport">', { selector: 'meta[name="viewport"]', ...(value ? { evidence: value } : {}) });
38
+ };
39
+ export const seoCanonical = ({ $ }) => {
40
+ const href = $('link[rel="canonical"]').first().attr("href")?.trim();
41
+ const selector = 'link[rel="canonical"]';
42
+ if (!href)
43
+ return result("seo/canonical", "error", false, 'Page has no <link rel="canonical">', { selector });
44
+ const ok = isAbsoluteHttpUrl(href);
45
+ return result("seo/canonical", "error", ok, ok ? "Canonical URL is absolute" : "Canonical URL is not an absolute http(s) URL", { selector, evidence: href });
46
+ };
47
+ export const seoOpenGraph = ({ $ }) => {
48
+ const problems = [];
49
+ for (const key of ["og:title", "og:description", "og:url"]) {
50
+ if (!metaContent($, key))
51
+ problems.push(`${key} missing`);
52
+ }
53
+ const image = metaContent($, "og:image");
54
+ if (!image)
55
+ problems.push("og:image missing");
56
+ else if (!isAbsoluteHttpUrl(image))
57
+ problems.push(`og:image is not absolute (${image})`);
58
+ return result("seo/open-graph", "warn", problems.length === 0, problems.length === 0 ? "Open Graph tags are complete" : "Open Graph tags are incomplete", problems.length ? { evidence: problems.join("; ") } : {});
59
+ };
60
+ export const seoTwitterCard = ({ $ }) => {
61
+ const value = metaContent($, "twitter:card");
62
+ return result("seo/twitter-card", "warn", value !== undefined, value ? `twitter:card is ${value}` : 'Page has no <meta name="twitter:card">', { selector: 'meta[name="twitter:card"]' });
63
+ };
64
+ export const seoJsonLd = ({ $ }) => {
65
+ const { valid, invalid } = jsonLdBlocks($);
66
+ const selector = 'script[type="application/ld+json"]';
67
+ if (valid.length === 0 && invalid === 0) {
68
+ return result("seo/json-ld", "warn", false, "Page has no JSON-LD structured data", { selector });
69
+ }
70
+ return result("seo/json-ld", "warn", invalid === 0, invalid === 0 ? "JSON-LD blocks parse" : `${invalid} JSON-LD block(s) are not valid JSON`, { selector });
71
+ };
72
+ export const seoJsonLdType = ({ $ }) => {
73
+ const blocks = jsonLdBlocks($).valid;
74
+ if (blocks.length === 0)
75
+ return notApplicable("seo/json-ld-type", "No valid JSON-LD to check for a @type (see seo/json-ld)");
76
+ const types = blocks.flatMap(jsonLdTypes);
77
+ const ok = types.some((type) => JSON_LD_TYPES.includes(type));
78
+ return result("seo/json-ld-type", "warn", ok, ok
79
+ ? "JSON-LD describes the site or product"
80
+ : `JSON-LD has no @type of ${JSON_LD_TYPES.join(", ")}`, types.length ? { evidence: `found: ${types.join(", ")}` } : {});
81
+ };
82
+ export const seoH1 = ({ $ }) => {
83
+ const count = $("h1").length;
84
+ return result("seo/h1", "error", count === 1, count === 1 ? "Page has exactly one h1" : `Page has ${count} h1 elements, expected exactly one`, { selector: "h1" });
85
+ };
86
+ export const seoHeadingOrder = ({ $ }) => {
87
+ const skips = [];
88
+ let previous;
89
+ $("h1, h2, h3, h4, h5, h6").each((_, el) => {
90
+ const level = Number(el.tagName.slice(1));
91
+ if (previous !== undefined && level > previous + 1)
92
+ skips.push(`h${previous} -> h${level}`);
93
+ previous = level;
94
+ });
95
+ return result("seo/heading-order", "warn", skips.length === 0, skips.length === 0 ? "Heading levels are not skipped" : "Heading levels are skipped", skips.length ? { evidence: skips.join(", ") } : {});
96
+ };
97
+ export const seoImgAlt = ({ $ }) => {
98
+ const missing = $("img:not([alt])")
99
+ .map((_, el) => $(el).attr("src") ?? "(no src)")
100
+ .get();
101
+ return result("seo/img-alt", "warn", missing.length === 0, missing.length === 0 ? "All images have alt text" : `${missing.length} image(s) have no alt attribute`, { selector: "img:not([alt])", ...(missing.length ? { evidence: missing.slice(0, 10).join(", ") } : {}) });
102
+ };
103
+ export const seoFavicon = ({ $ }) => {
104
+ const found = $("link[rel]").filter((_, el) => ($(el).attr("rel") ?? "").toLowerCase().split(/\s+/).includes("icon"));
105
+ return result("seo/favicon", "warn", found.length > 0, found.length > 0 ? "Page links a favicon" : 'Page has no <link rel="icon">');
106
+ };
107
+ // Directives that take a value, so "max-image-preview:none" is not a "<bot>: none" pair.
108
+ const VALUE_DIRECTIVES = new Set(["max-snippet", "max-image-preview", "max-video-preview", "unavailable_after"]);
109
+ export function blocksIndexing(directives) {
110
+ return directives.split(",").some((part) => {
111
+ let token = part.trim().toLowerCase();
112
+ const prefixed = /^([a-z0-9_-]+)\s*:\s*(.*)$/.exec(token);
113
+ if (prefixed && !VALUE_DIRECTIVES.has(prefixed[1] ?? ""))
114
+ token = prefixed[2] ?? "";
115
+ return token === "noindex" || token === "none";
116
+ });
117
+ }
118
+ export const seoNoindex = ({ $, headers }) => {
119
+ const sources = [];
120
+ $('meta[name="robots" i], meta[name="googlebot" i]').each((_, el) => {
121
+ const content = $(el).attr("content") ?? "";
122
+ if (blocksIndexing(content))
123
+ sources.push(`meta ${$(el).attr("name")}: ${content}`);
124
+ });
125
+ const header = headers?.["x-robots-tag"];
126
+ if (header && blocksIndexing(header))
127
+ sources.push(`X-Robots-Tag: ${header}`);
128
+ return result("seo/noindex", "error", sources.length === 0, sources.length === 0 ? "Page can be indexed" : "Page tells search engines not to index it", sources.length ? { evidence: sources.join("; ") } : {});
129
+ };
130
+ export const seoRobotsTxt = ({ url, robotsTxt }) => {
131
+ const robotsUrl = new URL("/robots.txt", url).href;
132
+ return result("seo/robots-txt", "error", validText(robotsTxt), textStatusMessage("robots.txt", robotsTxt), {
133
+ url: robotsUrl,
134
+ });
135
+ };
136
+ export const seoRobotsSitemap = ({ url, robotsTxt }) => {
137
+ if (!validText(robotsTxt)) {
138
+ return notApplicable("seo/robots-sitemap", "No robots.txt to check for a Sitemap: line (see seo/robots-txt)", {
139
+ url: new URL("/robots.txt", url).href,
140
+ });
141
+ }
142
+ const sitemaps = parseRobots(robotsTxt.body).sitemaps;
143
+ return result("seo/robots-sitemap", "warn", sitemaps.length > 0, sitemaps.length > 0 ? "robots.txt lists a sitemap" : "robots.txt has no Sitemap: line", { url: new URL("/robots.txt", url).href, ...(sitemaps.length ? { evidence: sitemaps.join(", ") } : {}) });
144
+ };
145
+ export function parseSitemap(body) {
146
+ let $;
147
+ try {
148
+ $ = load(body, { xml: true });
149
+ }
150
+ catch {
151
+ return undefined;
152
+ }
153
+ const root = $.root().children().first();
154
+ const name = root.prop("tagName")?.toLowerCase();
155
+ if (name !== "urlset" && name !== "sitemapindex")
156
+ return undefined;
157
+ const entryTag = name === "urlset" ? "url" : "sitemap";
158
+ const entries = root.children(entryTag);
159
+ const missingLastmod = entries
160
+ .filter((_, el) => !$(el).children("lastmod").text().trim())
161
+ .map((_, el) => $(el).children("loc").text().trim() || "(no loc)")
162
+ .get();
163
+ return { kind: name, entries: entries.length, missingLastmod };
164
+ }
165
+ export const seoSitemap = ({ sitemap }) => {
166
+ const extra = sitemap ? { url: sitemap.url } : {};
167
+ if (sitemap?.status !== 200) {
168
+ return result("seo/sitemap", "error", false, `Sitemap returned ${sitemap?.status ?? "no response"}`, extra);
169
+ }
170
+ if (isHtmlPage(sitemap))
171
+ return result("seo/sitemap", "error", false, htmlFallbackMessage("sitemap.xml"), extra);
172
+ const doc = parseSitemap(sitemap.body);
173
+ return result("seo/sitemap", "error", doc !== undefined, doc ? `Sitemap is a valid ${doc.kind} with ${doc.entries} entries` : "Sitemap is not a <urlset> or <sitemapindex>", extra);
174
+ };
175
+ export const seoSitemapLastmod = ({ sitemap }) => {
176
+ const extra = sitemap ? { url: sitemap.url } : {};
177
+ const doc = validText(sitemap) ? parseSitemap(sitemap.body) : undefined;
178
+ if (!doc)
179
+ return notApplicable("seo/sitemap-lastmod", "No valid sitemap to check lastmod (see seo/sitemap)", extra);
180
+ const missing = doc.missingLastmod;
181
+ return result("seo/sitemap-lastmod", "warn", missing.length === 0 && doc.entries > 0, doc.entries === 0
182
+ ? "Sitemap has no entries"
183
+ : missing.length === 0
184
+ ? "Every sitemap entry has lastmod"
185
+ : `${missing.length} of ${doc.entries} sitemap entries have no lastmod`, { ...extra, ...(missing.length ? { evidence: missing.slice(0, 10).join(", ") } : {}) });
186
+ };
187
+ export const seoRules = [
188
+ seoTitle,
189
+ seoTitleLength,
190
+ seoMetaDescription,
191
+ seoMetaDescriptionLength,
192
+ seoHtmlLang,
193
+ seoViewport,
194
+ seoCanonical,
195
+ seoOpenGraph,
196
+ seoTwitterCard,
197
+ seoJsonLd,
198
+ seoJsonLdType,
199
+ seoH1,
200
+ seoHeadingOrder,
201
+ seoImgAlt,
202
+ seoFavicon,
203
+ seoNoindex,
204
+ seoRobotsTxt,
205
+ seoRobotsSitemap,
206
+ seoSitemap,
207
+ seoSitemapLastmod,
208
+ ];
@@ -0,0 +1,55 @@
1
+ import type { CheerioAPI } from "cheerio";
2
+ import type { Category, Confidence, Engine, Fix, Framework, PageType, Severity } from "../report.js";
3
+ export interface TextResource {
4
+ status: number;
5
+ body: string;
6
+ contentType?: string;
7
+ }
8
+ export interface PageContext {
9
+ url: string;
10
+ html: string;
11
+ $: CheerioAPI;
12
+ headers?: Record<string, string>;
13
+ robotsTxt?: TextResource;
14
+ sitemap?: TextResource & {
15
+ url: string;
16
+ };
17
+ llmsTxt?: TextResource;
18
+ llmsFullTxt?: TextResource;
19
+ framework: Framework;
20
+ pageType?: PageType;
21
+ linkChecks?: LinkCheck[];
22
+ }
23
+ export interface LinkCheck {
24
+ url: string;
25
+ status: number;
26
+ }
27
+ export interface RuleResult {
28
+ id: string;
29
+ category: Category;
30
+ severity: Severity;
31
+ pass: boolean;
32
+ message: string;
33
+ evidence?: string;
34
+ selector?: string;
35
+ url?: string;
36
+ fix?: Fix;
37
+ engine?: Engine;
38
+ confidence?: Confidence;
39
+ source?: string;
40
+ needsOwner?: boolean;
41
+ }
42
+ export type Rule = (ctx: PageContext) => RuleResult;
43
+ export declare function result(id: string, severity: Severity, pass: boolean, message: string, extra?: Pick<RuleResult, "evidence" | "selector" | "url" | "fix" | "engine" | "confidence" | "source" | "needsOwner">): RuleResult;
44
+ export declare function notApplicable(id: string, message: string, extra?: Pick<RuleResult, "evidence" | "selector" | "url" | "engine" | "confidence" | "source">): RuleResult;
45
+ export declare function isAbsoluteHttpUrl(value: string | undefined): boolean;
46
+ export declare function metaContent($: CheerioAPI, key: string): string | undefined;
47
+ export declare function isHtmlPage(res: TextResource): boolean;
48
+ export declare function htmlFallbackMessage(file: string): string;
49
+ export declare function validText(res: TextResource | undefined): res is TextResource;
50
+ export declare function textStatusMessage(file: string, res: TextResource | undefined): string;
51
+ export declare function jsonLdBlocks($: CheerioAPI): {
52
+ valid: unknown[];
53
+ invalid: number;
54
+ };
55
+ export declare function jsonLdTypes(data: unknown): string[];
@@ -0,0 +1,78 @@
1
+ export function result(id, severity, pass, message, extra = {}) {
2
+ const category = id.split("/")[0];
3
+ return { id, category, severity, pass, message, ...extra };
4
+ }
5
+ // A rule that depends on another rule's subject (a sitemap, llms.txt, robots.txt, JSON-LD, a form) when that
6
+ // subject is missing: an info pass, so it weighs 0 and the missing subject is counted once, by its own rule.
7
+ export function notApplicable(id, message, extra = {}) {
8
+ return result(id, "info", true, message, extra);
9
+ }
10
+ export function isAbsoluteHttpUrl(value) {
11
+ if (!value)
12
+ return false;
13
+ try {
14
+ const parsed = new URL(value);
15
+ return parsed.protocol === "http:" || parsed.protocol === "https:";
16
+ }
17
+ catch {
18
+ return false;
19
+ }
20
+ }
21
+ export function metaContent($, key) {
22
+ const value = $(`meta[name="${key}" i], meta[property="${key}" i]`).first().attr("content")?.trim();
23
+ return value ? value : undefined;
24
+ }
25
+ // An app that answers every path with its HTML shell returns 200 for /robots.txt and friends.
26
+ export function isHtmlPage(res) {
27
+ const head = res.body.replace(/^\uFEFF/, "").trimStart().slice(0, 2048).toLowerCase();
28
+ if (/^<(\?xml|urlset|sitemapindex)\b/.test(head) && !head.includes("<html"))
29
+ return false;
30
+ if (res.contentType?.toLowerCase().includes("text/html"))
31
+ return true;
32
+ return head.startsWith("<") && (head.includes("<html") || head.includes("<!doctype"));
33
+ }
34
+ export function htmlFallbackMessage(file) {
35
+ return `${file} returned an HTML page (probably an app fallback), not a ${file.replace(/^\//, "")} file`;
36
+ }
37
+ export function validText(res) {
38
+ return res?.status === 200 && !isHtmlPage(res);
39
+ }
40
+ export function textStatusMessage(file, res) {
41
+ if (res?.status === 200)
42
+ return isHtmlPage(res) ? htmlFallbackMessage(file) : `${file} returns 200`;
43
+ return `${file} returned ${res?.status ?? "no response"}`;
44
+ }
45
+ export function jsonLdBlocks($) {
46
+ const valid = [];
47
+ let invalid = 0;
48
+ $('script[type="application/ld+json"]').each((_, el) => {
49
+ try {
50
+ valid.push(JSON.parse($(el).text()));
51
+ }
52
+ catch {
53
+ invalid += 1;
54
+ }
55
+ });
56
+ return { valid, invalid };
57
+ }
58
+ export function jsonLdTypes(data) {
59
+ const types = [];
60
+ const walk = (node) => {
61
+ if (Array.isArray(node)) {
62
+ node.forEach(walk);
63
+ return;
64
+ }
65
+ if (node === null || typeof node !== "object")
66
+ return;
67
+ const record = node;
68
+ const type = record["@type"];
69
+ if (typeof type === "string")
70
+ types.push(type);
71
+ if (Array.isArray(type))
72
+ types.push(...type.filter((t) => typeof t === "string"));
73
+ if (record["@graph"] !== undefined)
74
+ walk(record["@graph"]);
75
+ };
76
+ walk(data);
77
+ return types;
78
+ }
@@ -0,0 +1,6 @@
1
+ import type { Category, Confidence, Severity } from "./report.js";
2
+ import type { RuleResult } from "./rules/types.js";
3
+ export declare const WEIGHTS: Record<Severity, number>;
4
+ export declare const CONFIDENCE_WEIGHTS: Record<Confidence, number>;
5
+ export declare function resultWeight(item: Pick<RuleResult, "category" | "severity" | "confidence">): number;
6
+ export declare function scoreCategory(results: RuleResult[], category: Category): number;
package/dist/score.js ADDED
@@ -0,0 +1,23 @@
1
+ export const WEIGHTS = { error: 3, warn: 1, info: 0 };
2
+ // The convert score weights checks by how strong their evidence is, not by severity: a medium-confidence
3
+ // warn counts less than a high-confidence one. Info results still weigh 0 there, like in every category, so
4
+ // a tip never moves the score. A convert result without a confidence counts as high.
5
+ export const CONFIDENCE_WEIGHTS = { high: 3, medium: 2, low: 1 };
6
+ export function resultWeight(item) {
7
+ if (item.category !== "convert")
8
+ return WEIGHTS[item.severity];
9
+ return item.severity === "info" ? 0 : CONFIDENCE_WEIGHTS[item.confidence ?? "high"];
10
+ }
11
+ export function scoreCategory(results, category) {
12
+ let total = 0;
13
+ let passed = 0;
14
+ for (const item of results) {
15
+ if (item.category !== category)
16
+ continue;
17
+ const weight = resultWeight(item);
18
+ total += weight;
19
+ if (item.pass)
20
+ passed += weight;
21
+ }
22
+ return total === 0 ? 100 : Math.round((100 * passed) / total);
23
+ }
@@ -0,0 +1,9 @@
1
+ export declare const SKILL_NAME = "sugikit";
2
+ export declare const SKILLS_SOURCE: string;
3
+ export interface SkillInstall {
4
+ source: string;
5
+ target: string;
6
+ replaced: boolean;
7
+ files: string[];
8
+ }
9
+ export declare function installSkills(projectDir: string, source?: string): Promise<SkillInstall>;
package/dist/skills.js ADDED
@@ -0,0 +1,22 @@
1
+ import { existsSync } from "node:fs";
2
+ import { cp, readdir, rm } from "node:fs/promises";
3
+ import { join, relative } from "node:path";
4
+ import { fileURLToPath } from "node:url";
5
+ export const SKILL_NAME = "sugikit";
6
+ // src/ and dist/ both sit one level below the package root, next to skills/.
7
+ export const SKILLS_SOURCE = fileURLToPath(new URL(`../skills/${SKILL_NAME}`, import.meta.url));
8
+ export async function installSkills(projectDir, source = SKILLS_SOURCE) {
9
+ if (!existsSync(join(source, "SKILL.md")))
10
+ throw new Error(`packaged skill not found at ${source}`);
11
+ const target = join(projectDir, ".claude", "skills", SKILL_NAME);
12
+ const replaced = existsSync(target);
13
+ if (replaced)
14
+ await rm(target, { recursive: true, force: true });
15
+ await cp(source, target, { recursive: true });
16
+ const entries = await readdir(target, { recursive: true, withFileTypes: true });
17
+ const files = entries
18
+ .filter((entry) => entry.isFile())
19
+ .map((entry) => relative(target, join(entry.parentPath, entry.name)))
20
+ .sort();
21
+ return { source, target, replaced, files };
22
+ }
package/package.json CHANGED
@@ -1,6 +1,66 @@
1
1
  {
2
2
  "name": "sugikit",
3
- "version": "0.0.1",
4
- "license": "MIT",
5
- "files": ["LICENSE"]
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Check and fix your landing page's polish, SEO, AI search and PageSpeed with your coding agent.",
5
+ "keywords": [
6
+ "landing-page",
7
+ "seo",
8
+ "ai-search",
9
+ "pagespeed",
10
+ "lighthouse",
11
+ "accessibility",
12
+ "coding-agent",
13
+ "cli"
14
+ ],
15
+ "license": "SEE LICENSE IN LICENSE",
16
+ "homepage": "https://sugikit.com",
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/mertbuilds/sugikit.git",
20
+ "directory": "packages/cli"
21
+ },
22
+ "type": "module",
23
+ "bin": {
24
+ "sugikit": "dist/index.js"
25
+ },
26
+ "exports": {
27
+ "./rules": {
28
+ "types": "./dist/api/rules.d.ts",
29
+ "default": "./dist/api/rules.js"
30
+ },
31
+ "./browser": {
32
+ "types": "./dist/api/browser.d.ts",
33
+ "default": "./dist/api/browser.js"
34
+ },
35
+ "./package.json": "./package.json"
36
+ },
37
+ "files": [
38
+ "dist",
39
+ "skills"
40
+ ],
41
+ "engines": {
42
+ "node": ">=22"
43
+ },
44
+ "publishConfig": {
45
+ "access": "public"
46
+ },
47
+ "dependencies": {
48
+ "@axe-core/playwright": "4.14.0",
49
+ "axe-core": "4.14.1",
50
+ "cheerio": "1.2.0",
51
+ "playwright": "1.65.1",
52
+ "undici": "8.13.0",
53
+ "zod": "4.6.7"
54
+ },
55
+ "devDependencies": {
56
+ "@types/node": "26.6.6",
57
+ "esbuild": "0.28.2",
58
+ "typescript": "7.0.2",
59
+ "vitest": "5.1.1"
60
+ },
61
+ "scripts": {
62
+ "build": "tsc -p tsconfig.build.json && node scripts/stamp-release.mjs",
63
+ "typecheck": "tsc -p tsconfig.json",
64
+ "test": "vitest run"
65
+ }
66
+ }
@@ -0,0 +1,9 @@
1
+ Set up Sugikit in this project and use it to check and fix the landing page.
2
+
3
+ 1. Find the package manager from the lockfile (pnpm-lock.yaml, yarn.lock, bun.lock, package-lock.json). Install `{{PACKAGE}}` as a dev dependency with it. Examples: `pnpm add -D {{PACKAGE}}`, `npm install -D {{PACKAGE}}`.
4
+ 2. Run `npx sugikit skills install`. It copies the sugikit skill into `.claude/skills/sugikit`.
5
+ 3. Check that Playwright Chromium is installed. If `npx sugikit check` reports that Chromium is missing, or you are not sure, run `npx sugikit browsers install`. It installs the Chromium build that Sugikit's own Playwright version needs (`npx playwright install` can fetch a newer Playwright with a different build).
6
+ 4. Add `.sugikit/` to `.gitignore` if it is not there.
7
+ 5. Read `.claude/skills/sugikit/SKILL.md` and follow it. Start the dev server if it is not running, then run the fix loop on the landing page.
8
+
9
+ Rules: keep the site's look. Fix only what Sugikit measures. Never invent content. Ask me once, in one message, for any facts you need (production domain, organization name). End with the before and after scores.
@@ -0,0 +1,147 @@
1
+ ---
2
+ name: sugikit
3
+ description: Check and fix a landing page or marketing site with the Sugikit CLI. Measures polish (layout, contrast, tap targets, type, dark mode, motion), SEO (meta tags, canonical, sitemap, robots, JSON-LD), GEO (llms.txt, AI crawlers, server-rendered content), conversion (dead links, placeholder text, contact, form length, price) and PageSpeed, then fixes the findings one rule at a time while keeping the site's look. Use when the user asks to check, audit, polish, fix or improve the SEO, GEO, AI search visibility, accessibility, conversion or PageSpeed of a landing page, marketing site or product homepage, or says "run sugikit" or "run Sugikit".
4
+ ---
5
+
6
+ # sugikit
7
+
8
+ `sugikit` measures a page and writes a JSON report. You fix what it measures, then measure again. The report is the source of truth. Do not fix things the report does not flag.
9
+
10
+ ## Commands
11
+
12
+ - `npx sugikit check <url> [--project <dir>] [--out <file>] [--no-browser] [--psi] [--runs N] [--page-type product|launch|waitlist]`: writes a JSON report (default `.sugikit/report.json`) and screenshots in `<report name>-shots/` next to the report (`.sugikit/report-shots/`, or `.sugikit/before-shots/` for `--out .sugikit/before.json`). Exits 1 when error findings exist. That exit code is expected while errors remain. `--page-type` overrides the detected page type for the convert checks.
13
+ - `npx sugikit psi <url> [--project <dir>] [--out <file>] [--runs N]`: PageSpeed Insights only (default `.sugikit/psi.json`), best score of 3 runs per strategy. Needs `PSI_API_KEY` and a public URL.
14
+ - `npx sugikit report [--before <file>] [--after <file>] [--psi-before <file>] [--psi-after <file>] [--out <file>]`: builds a local before/after HTML page (default `.sugikit/report.html`) from `.sugikit/before.json` and `.sugikit/report.json`, and prints its path.
15
+ - `npx sugikit browsers install`: installs the headless Chromium build that Sugikit's pinned Playwright version needs. Use it instead of `npx playwright install`.
16
+
17
+ Report shape: `scores` `{ polish, seo, geo, convert, pagespeed? }` (pagespeed has `mobile` and `desktop`, each with `performance`, `accessibility`, `bestPractices`, `seo`), `framework` (`next`, `tanstack-start` or `unknown`), `pageType` (`product`, `launch` or `waitlist`), `findings[]` with `id`, `category`, `severity` (`error`, `warn`, `info`), `message`, `selector`, `url`, `evidence` and `fix` `{ summary, framework?, files? }`. Convert findings also have `engine`, `confidence` (`high`, `medium`, `low`), `source` and `needsOwner`. `screenshots[]` lists the PNG per state (`desktop-light`, `desktop-dark`, `phone-light`, `phone-dark`).
18
+
19
+ ## The fix loop
20
+
21
+ ### 1. Find the URL and the framework
22
+
23
+ - Read `package.json` scripts. `next dev` means Next.js. `vite dev` with `@tanstack/react-start` means TanStack Start.
24
+ - Check if the dev server already runs (`curl -sI <url>`). If not, start the `dev` script in the background and wait until the URL answers.
25
+ - Use the URL the dev script prints. Pass `--project <dir>` when the app is not in the current directory (for example in a monorepo).
26
+ - Open the framework reference: `references/next.md` or `references/tanstack-start.md`.
27
+
28
+ ### 2. Save a baseline (first run only)
29
+
30
+ ```sh
31
+ npx sugikit check <url> --out .sugikit/before.json
32
+ ```
33
+
34
+ The screenshots go to `.sugikit/before-shots/` on their own.
35
+
36
+ Never overwrite `.sugikit/before.json` or `.sugikit/before-shots/`. If they exist, a baseline is already saved. Skip this step.
37
+
38
+ ### 3. Read the report and fix
39
+
40
+ Read `.sugikit/report.json` (or `.sugikit/before.json` on the first round). Then:
41
+
42
+ 1. Take findings in this order: `error`, then `warn`. `info` findings are optional. Fix them only when the fix is small and safe.
43
+ 2. Work one rule id at a time. Read the finding's `message`, `evidence`, `selector`, `fix.summary` and `fix.files`.
44
+ 3. Open the reference for its category: `references/polish.md`, `references/seo.md`, `references/geo.md`, `references/convert.md`, `references/pagespeed.md`. Use the framework reference for the code.
45
+ 4. Make the smallest change that fixes the measured problem. Edit the files the project already has. Follow the project's code style.
46
+ 5. If a fix needs facts the page does not have, do not guess. Collect the question and go on with other rules (see Questions below).
47
+ 6. A finding with `needsOwner: true` needs facts only the owner has. Do not try to fix it again in later rounds. Put it on the "your turn" list (see Summary).
48
+
49
+ ### 4. Measure again
50
+
51
+ ```sh
52
+ npx sugikit check <url> --out .sugikit/report.json
53
+ ```
54
+
55
+ Run it after each batch of fixes. Compare with the last report: the fixed rules must pass, and no new finding may appear. If a fix made something else fail, fix or revert it before you continue.
56
+
57
+ Stop when there are no `error` findings and every category score is 90 or higher, or after 5 rounds. Five rounds is the limit, even if findings remain.
58
+
59
+ Never game the check:
60
+
61
+ - Do not hide elements from the checker or from crawlers.
62
+ - Do not sniff the user agent or serve different content to bots.
63
+ - Do not add fake or filler content to pass a length or text rule.
64
+ - Do not disable a rule, edit Sugikit, or edit the report.
65
+
66
+ ### 5. Check the production build
67
+
68
+ Dev servers differ from production (dev scripts, missing minification, different headers). Build and serve the production build, then check once more:
69
+
70
+ - Next.js: `next build && next start` (use the project's `build` and `start` scripts).
71
+ - TanStack Start: `vite build`, then the project's `start` or `preview` script (`vite preview`, or `node .output/server/index.mjs`).
72
+
73
+ ```sh
74
+ npx sugikit check <prod-url> --out .sugikit/prod/report.json
75
+ ```
76
+
77
+ Fix any finding that only shows in production. Stop the production server when done. Leave the dev server as you found it.
78
+
79
+ ### 6. PageSpeed
80
+
81
+ PageSpeed Insights needs a public URL. A localhost URL does not work.
82
+
83
+ - If the site has a public URL (a deploy preview or production) and `PSI_API_KEY` is set: `npx sugikit psi <public-url> --out .sugikit/psi.json`. Its findings are `pagespeed/<lighthouse-audit-id>`. Fix them with `references/pagespeed.md`. Fixes only show after a new deploy, so list them and ask the user to redeploy before you run it again.
84
+ - If not: tell the user to deploy a preview, set `PSI_API_KEY` (free key: https://developers.google.com/speed/docs/insights/v5/get-started), and run `npx sugikit psi <public-url>`.
85
+
86
+ ### 7. Summary
87
+
88
+ End with a short summary:
89
+
90
+ | Category | Before | After |
91
+ |---|---|---|
92
+ | polish | | |
93
+ | seo | | |
94
+ | geo | | |
95
+ | convert | | |
96
+ | pagespeed | | |
97
+
98
+ Then list:
99
+
100
+ - Findings fixed: rule id and one line on the change.
101
+ - Findings left: rule id and the reason (needs an answer from the user, would need a redesign, out of scope).
102
+ - Your turn: every finding with `needsOwner: true`, rule id and the one fact you need from the owner ("the support email address", "the price per month").
103
+ - Copy suggestions you did not apply (see Conversion policy), with the old and new text.
104
+ - Visible design changes (see Taste rules), with old and new values.
105
+ - Screenshot paths: `.sugikit/before-shots/`, `.sugikit/report-shots/`, `.sugikit/prod/report-shots/`.
106
+
107
+ Then run `npx sugikit report` and give the user the path of the HTML page it prints.
108
+
109
+ ## Taste rules
110
+
111
+ The site's own look stays. You fix measurable problems only.
112
+
113
+ - No redesigns. No new color palette. No new fonts. No layout rewrites.
114
+ - No copy rewrites beyond what a rule needs. A missing meta description is written from the page's own words.
115
+ - When a fix visibly changes the design (contrast, type size, tap target size), choose the closest value that passes and keeps the brand. Darken or lighten the same hue. Do not switch to another color. Grow the hit area with padding before you grow the visible control.
116
+ - List each visible change for the user with the old and new value.
117
+ - Content that Sugikit makes you add (llms.txt, llms-full.txt, JSON-LD, FAQ schema, descriptions, alt text) must be true to the page. Never invent features, prices, reviews, ratings, customers or claims.
118
+ - Add FAQ schema only when the page has a real FAQ section. Do not write an FAQ to pass a rule.
119
+ - Keep features. Do not remove an animation, image, script or section to gain points without asking the user.
120
+
121
+ ## Conversion policy
122
+
123
+ These are hard rules. They apply to every fix, not only convert findings.
124
+
125
+ - Never invent proof, testimonials, user counts, logos, ratings, prices, guarantees, deadlines or urgency. No countdowns, no "only N left", no made up quotes or contact details. If a fact is not in the repo (README, pricing config, checkout setup, package.json, llms.txt), ask the owner.
126
+ - Keep the buyer's style. Fix conversion inside the existing palette, type and voice. Make a button stand out with contrast and space within the palette, never with a new loud color.
127
+ - Ask the owner for missing facts in one batched message (see Questions). Do not ask one at a time.
128
+ - Findings with `needsOwner: true` go to the "your turn" list in the final summary. Do not retry them.
129
+ - Copy edits (headlines, button labels, link text) are suggestions only. Apply them only when the owner allowed copy changes. Else list the suggested text in the summary.
130
+
131
+ ## Questions
132
+
133
+ Some fixes need facts the page does not have. Examples:
134
+
135
+ - The production domain (for canonical URLs, `metadataBase`, sitemap and robots `Sitemap:` lines, `og:url`, absolute `og:image`).
136
+ - The organization or product name and logo for JSON-LD, when the page does not say them.
137
+ - An Open Graph image, when the project has none.
138
+ - Whether a `noindex` or a crawler block is on purpose.
139
+ - Real values for convert findings with `needsOwner: true`: the contact address, the price, real names instead of placeholders.
140
+
141
+ Collect all such questions. Ask the user once, in one message, after the first pass of fixes. Do not ask one at a time. Until the user answers, leave those rules open and say so in the summary.
142
+
143
+ ## When Sugikit fails
144
+
145
+ - `polish/browser` finding: Chromium is missing or the page did not load. If Chromium is missing, run `npx sugikit browsers install` and check again. If the message names a TLS certificate error on a local URL, ask the user to trust the dev server's CA in the system trust store. Use `--no-browser` only if the install is not possible, and say that polish was skipped.
146
+ - `could not check <url>` or a failing `seo/http-status`: the server is not running or the URL is wrong. Fix that first.
147
+ - Framework `unknown`: use the generic `fix.summary` and the project's own structure. Read the category references for the HTML the page must produce.