@ibalzam/codejitsu-core 0.1.0

package/modules/seo/src/schema.ts

@@ -0,0 +1,203 @@
+/**
+ * JSON-LD schema.org builders. Each function returns a plain object ready
+ * to `JSON.stringify` and inject into a `<script type="application/ld+json">`.
+ *
+ * Helper at the bottom: `jsonLd(obj)` returns the stringified script body.
+ */
+
+export interface OrganizationInput {
+  name: string;
+  url: string;
+  logo?: string;
+  sameAs?: string[];
+  email?: string;
+  telephone?: string;
+}
+
+export function organization(input: OrganizationInput) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    name: input.name,
+    url: input.url,
+    ...(input.logo && { logo: input.logo }),
+    ...(input.sameAs && { sameAs: input.sameAs }),
+    ...(input.email && { email: input.email }),
+    ...(input.telephone && { telephone: input.telephone }),
+  };
+}
+
+export interface PostalAddress {
+  streetAddress?: string;
+  addressLocality: string;
+  addressRegion?: string;
+  postalCode?: string;
+  addressCountry: string;
+}
+
+export interface GeoCoordinates {
+  latitude: number;
+  longitude: number;
+}
+
+export interface LocalBusinessInput {
+  name: string;
+  url: string;
+  telephone: string;
+  image?: string;
+  priceRange?: string;
+  address: PostalAddress;
+  geo?: GeoCoordinates;
+  openingHours?: string[];
+  areaServed?: string[];
+  sameAs?: string[];
+  /** Override @type to a more specific LocalBusiness subtype, e.g. 'HVACBusiness', 'HomeAndConstructionBusiness'. */
+  type?: string;
+}
+
+export function localBusiness(input: LocalBusinessInput) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': input.type ?? 'LocalBusiness',
+    name: input.name,
+    url: input.url,
+    telephone: input.telephone,
+    ...(input.image && { image: input.image }),
+    ...(input.priceRange && { priceRange: input.priceRange }),
+    address: { '@type': 'PostalAddress', ...input.address },
+    ...(input.geo && { geo: { '@type': 'GeoCoordinates', ...input.geo } }),
+    ...(input.openingHours && { openingHoursSpecification: input.openingHours }),
+    ...(input.areaServed && { areaServed: input.areaServed }),
+    ...(input.sameAs && { sameAs: input.sameAs }),
+  };
+}
+
+export interface WebSiteInput {
+  name: string;
+  url: string;
+  /** If set, adds SearchAction pointing to this URL template (with `{search_term_string}`). */
+  searchUrlTemplate?: string;
+}
+
+export function website(input: WebSiteInput) {
+  const base: Record<string, unknown> = {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    name: input.name,
+    url: input.url,
+  };
+  if (input.searchUrlTemplate) {
+    base.potentialAction = {
+      '@type': 'SearchAction',
+      target: { '@type': 'EntryPoint', urlTemplate: input.searchUrlTemplate },
+      'query-input': 'required name=search_term_string',
+    };
+  }
+  return base;
+}
+
+export interface BlogPostingInput {
+  title: string;
+  description: string;
+  url: string;
+  datePublished: string;
+  dateModified?: string;
+  image?: string;
+  authorName?: string;
+  publisherName: string;
+  publisherLogo?: string;
+}
+
+export function blogPosting(input: BlogPostingInput) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    headline: input.title,
+    description: input.description,
+    mainEntityOfPage: { '@type': 'WebPage', '@id': input.url },
+    url: input.url,
+    datePublished: input.datePublished,
+    dateModified: input.dateModified ?? input.datePublished,
+    ...(input.image && { image: input.image }),
+    ...(input.authorName && {
+      author: { '@type': 'Person', name: input.authorName },
+    }),
+    publisher: {
+      '@type': 'Organization',
+      name: input.publisherName,
+      ...(input.publisherLogo && {
+        logo: { '@type': 'ImageObject', url: input.publisherLogo },
+      }),
+    },
+  };
+}
+
+export interface FAQ {
+  question: string;
+  answer: string;
+}
+
+export function faqPage(faqs: FAQ[]) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: faqs.map((faq) => ({
+      '@type': 'Question',
+      name: faq.question,
+      acceptedAnswer: {
+        '@type': 'Answer',
+        text: faq.answer,
+      },
+    })),
+  };
+}
+
+export interface BreadcrumbItem {
+  name: string;
+  url: string;
+}
+
+export function breadcrumbList(items: BreadcrumbItem[]) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((item, i) => ({
+      '@type': 'ListItem',
+      position: i + 1,
+      name: item.name,
+      item: item.url,
+    })),
+  };
+}
+
+export interface ServiceInput {
+  name: string;
+  description: string;
+  url: string;
+  provider: { name: string; url: string };
+  areaServed?: string[];
+  serviceType?: string;
+}
+
+export function service(input: ServiceInput) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Service',
+    name: input.name,
+    description: input.description,
+    url: input.url,
+    provider: {
+      '@type': 'Organization',
+      name: input.provider.name,
+      url: input.provider.url,
+    },
+    ...(input.areaServed && { areaServed: input.areaServed }),
+    ...(input.serviceType && { serviceType: input.serviceType }),
+  };
+}
+
+/** Stringify a schema object for safe injection into <script type="application/ld+json">. */
+export function jsonLd(schema: unknown): string {
+  // Escape `</` to prevent breakout from the script tag.
+  return JSON.stringify(schema).replace(/<\//g, '<\\/');
+}

package/modules/seo/src/sitemap.ts

@@ -0,0 +1,109 @@
+/**
+ * Helpers for the `@astrojs/sitemap` integration.
+ *
+ * Two complementary functions:
+ *   - `defaultPriorityRules(site)` produces a `serialize` function that sets
+ *     priority and changefreq based on URL shape (home, top-level hubs,
+ *     service/area pages, blog posts).
+ *   - `excludeFuturePosts(futureSlugs)` produces a `filter` function that
+ *     drops scheduled blog posts whose slugs are in the supplied set.
+ *
+ * Compose both like:
+ *
+ *   sitemap({
+ *     filter: excludeFuturePosts(await blog.getFutureBlogSlugs()),
+ *     serialize: defaultPriorityRules(SITE),
+ *   })
+ */
+
+export interface SitemapItem {
+  url: string;
+  changefreq?:
+    | 'always'
+    | 'hourly'
+    | 'daily'
+    | 'weekly'
+    | 'monthly'
+    | 'yearly'
+    | 'never';
+  priority?: number;
+  lastmod?: string;
+}
+
+export interface PriorityRulesOptions {
+  /** Extra patterns appended to the defaults. Earlier entries win. */
+  rules?: Array<{ pattern: RegExp; priority: number; changefreq?: SitemapItem['changefreq'] }>;
+}
+
+/**
+ * Returns a `serialize` function that assigns priority/changefreq based on
+ * URL shape. Tune via `options.rules` for site-specific top-level paths.
+ *
+ * @param site The site origin (no trailing slash), e.g. 'https://example.com'.
+ */
+export function defaultPriorityRules(
+  site: string,
+  options: PriorityRulesOptions = {}
+) {
+  const homeUrl = `${site}/`;
+  const extra = options.rules ?? [];
+
+  return (item: SitemapItem): SitemapItem => {
+    if (item.url === homeUrl) {
+      return { ...item, priority: 1.0, changefreq: 'daily' };
+    }
+
+    for (const rule of extra) {
+      if (rule.pattern.test(item.url)) {
+        return {
+          ...item,
+          priority: rule.priority,
+          ...(rule.changefreq && { changefreq: rule.changefreq }),
+        };
+      }
+    }
+
+    // Default heuristics.
+    if (/\/(services|service-areas|industries)\/$/.test(item.url)) {
+      return { ...item, priority: 0.9, changefreq: 'weekly' };
+    }
+    if (/\/(services|service-areas|industries)\/[^/]+\/$/.test(item.url)) {
+      return { ...item, priority: 0.8, changefreq: 'weekly' };
+    }
+    if (/\/blog\/$/.test(item.url)) {
+      return { ...item, priority: 0.7, changefreq: 'daily' };
+    }
+    if (/\/blog\/[^/]+\/$/.test(item.url)) {
+      return { ...item, priority: 0.6, changefreq: 'monthly' };
+    }
+    if (/\/blog\/(tag|category)\/[^/]+\/$/.test(item.url)) {
+      return { ...item, priority: 0.5, changefreq: 'weekly' };
+    }
+    return item;
+  };
+}
+
+/**
+ * Returns a `filter` function for `@astrojs/sitemap` that excludes any URL
+ * whose final path segment matches a future-dated blog slug.
+ *
+ * Pass `await blog.getFutureBlogSlugs()` to the constructor.
+ */
+export function excludeFuturePosts(futureSlugs: string[]) {
+  const set = new Set(futureSlugs);
+  return (url: string): boolean => {
+    const m = url.match(/\/blog\/([^/]+)\/?$/);
+    if (!m) return true;
+    return !set.has(m[1]);
+  };
+}
+
+/** Compose multiple filter functions with AND semantics. */
+export function composeFilters(...filters: Array<(url: string) => boolean>) {
+  return (url: string) => filters.every((f) => f(url));
+}
+
+/** Filter helper: exclude URLs matching any of the supplied patterns. */
+export function excludePatterns(patterns: RegExp[]) {
+  return (url: string) => !patterns.some((p) => p.test(url));
+}

package/modules/seo/templates/Head.astro

@@ -0,0 +1,53 @@
+---
+import { jsonLd } from '@ibalzam/codejitsu-core/seo/schema';
+
+interface Props {
+  title: string;
+  description: string;
+  /** Absolute URL (with trailing slash). Defaults to current page. */
+  canonical?: string;
+  /** Absolute URL to OG image. */
+  ogImage?: string;
+  /** og:type. Defaults to 'website'. */
+  ogType?: 'website' | 'article';
+  /** JSON-LD schema objects to inject. Use builders from @ibalzam/codejitsu-core/seo/schema. */
+  schema?: unknown[];
+  /** Override <html lang>. Defaults to 'en'. */
+  noindex?: boolean;
+}
+
+const {
+  title,
+  description,
+  canonical,
+  ogImage,
+  ogType = 'website',
+  schema = [],
+  noindex = false,
+} = Astro.props;
+
+const canonicalUrl = canonical ?? new URL(Astro.url.pathname, Astro.site).toString();
+const absOgImage = ogImage
+  ? new URL(ogImage, Astro.site).toString()
+  : undefined;
+---
+
+<title>{title}</title>
+<meta name="description" content={description} />
+<link rel="canonical" href={canonicalUrl} />
+{noindex && <meta name="robots" content="noindex,follow" />}
+
+<meta property="og:title" content={title} />
+<meta property="og:description" content={description} />
+<meta property="og:url" content={canonicalUrl} />
+<meta property="og:type" content={ogType} />
+{absOgImage && <meta property="og:image" content={absOgImage} />}
+
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:title" content={title} />
+<meta name="twitter:description" content={description} />
+{absOgImage && <meta name="twitter:image" content={absOgImage} />}
+
+{schema.map((item) => (
+  <script type="application/ld+json" set:html={jsonLd(item)} />
+))}

package/modules/seo/templates/robots.txt

@@ -0,0 +1,5 @@
+User-agent: *
+Allow: /
+
+# Replace with your site's sitemap URL.
+Sitemap: https://example.com/sitemap-index.xml

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@ibalzam/codejitsu-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared core for Codejitsu Astro sites — reusable code and Claude-facing instructions for blog, SEO, images, deploy, and llms.txt.",
+  "keywords": [
+    "astro",
+    "blog",
+    "seo",
+    "schema.org",
+    "sitemap",
+    "llms.txt",
+    "cloudflare-pages",
+    "webp",
+    "claude"
+  ],
+  "license": "MIT",
+  "author": "Ika Balzam <ika@codejitsu.ca>",
+  "homepage": "https://github.com/ibalzam/codejitsu-site-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ibalzam/codejitsu-site-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ibalzam/codejitsu-site-kit/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./blog": "./modules/blog/src/index.ts",
+    "./blog/components": "./modules/blog/src/components/index.ts",
+    "./seo": "./modules/seo/src/index.ts",
+    "./seo/schema": "./modules/seo/src/schema.ts",
+    "./seo/sitemap": "./modules/seo/src/sitemap.ts",
+    "./images": "./modules/images/src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "codejitsu-llms": "./modules/llms/bin/generate.mjs",
+    "codejitsu-optimize-images": "./modules/images/bin/optimize.mjs",
+    "codejitsu-check": "./checklist/bin/run.mjs"
+  },
+  "files": [
+    "src",
+    "modules",
+    "checklist",
+    "MIGRATIONS",
+    "CLAUDE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "peerDependencies": {
+    "astro": ">=5.0.0"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "reading-time": "^1.5.0",
+    "sharp": "^0.33.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export const CORE_VERSION = '0.1.0';