@topy-ai/maggie 0.1.0

package/bin/maggie.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { cp } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SKILLS_ROOT = join(PACKAGE_ROOT, "bundled-skills");
+const REFERENCES_ROOT = join(PACKAGE_ROOT, "bundled-references");
+const TOOLS_ROOT = join(PACKAGE_ROOT, "bundled-tools");
+const SKILL_NAMES = [
+  "maggie-blog-bootstrap",
+  "maggie-clone",
+  "maggie-deployment",
+  "maggie-project-context",
+  "maggie-seo-geo",
+  "maggie-social-share",
+];
+
+function usage() {
+  console.log(`Maggie Skills installer
+
+Usage:
+  maggie init [--project PATH] [--agent auto|codex|claude|all] [--skills LIST]
+  maggie install [SKILL ...] [--project PATH] [--agent auto|codex|claude|all]
+  maggie list
+  maggie doctor [--project PATH]
+  maggie remove [SKILL ...] [--project PATH] [--agent codex|claude|all]
+
+Examples:
+  npx @topy-ai/maggie init
+  npx @topy-ai/maggie init --agent codex --skills maggie-blog-bootstrap,maggie-clone
+  npx @topy-ai/maggie doctor --project .
+`);
+}
+
+function option(args, name, fallback = undefined) {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : args[index + 1] ?? fallback;
+}
+
+function values(args, name) {
+  const value = option(args, name, "");
+  return value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
+}
+
+function projectRoot(args) {
+  return resolve(option(args, "--project", process.cwd()));
+}
+
+function selectedSkills(args) {
+  const requested = values(args, "--skills").concat(args.filter((item) => SKILL_NAMES.includes(item)));
+  const unique = [...new Set(requested)];
+  if (!unique.length) return SKILL_NAMES;
+  const invalid = unique.filter((name) => !SKILL_NAMES.includes(name));
+  if (invalid.length) throw new Error(`unknown skill: ${invalid.join(", ")}`);
+  return unique;
+}
+
+function agentRoots(args, root) {
+  const requested = option(args, "--agent", "auto");
+  if (!["auto", "codex", "claude", "all"].includes(requested)) throw new Error(`unknown agent: ${requested}`);
+  if (requested === "codex") return [join(root, ".agents")];
+  if (requested === "claude") return [join(root, ".claude")];
+  if (requested === "all") return [join(root, ".agents"), join(root, ".claude")];
+  const roots = [];
+  if (existsSync(join(root, ".agents"))) roots.push(join(root, ".agents"));
+  if (existsSync(join(root, ".claude"))) roots.push(join(root, ".claude"));
+  return roots.length ? roots : [join(root, ".agents")];
+}
+
+function copyIfMissing(source, target, force = false) {
+  if (existsSync(target) && !force) return "skipped";
+  mkdirSync(dirname(target), { recursive: true });
+  cp(source, target, { recursive: true, force });
+  return "installed";
+}
+
+function install(args) {
+  const root = projectRoot(args);
+  const skills = selectedSkills(args);
+  const force = args.includes("--force");
+  const roots = agentRoots(args, root);
+  if (!existsSync(SKILLS_ROOT)) throw new Error("bundled skills are missing; run npm pack from the package source");
+  for (const agentRoot of roots) {
+    for (const skill of skills) {
+      const result = copyIfMissing(join(SKILLS_ROOT, skill), join(agentRoot, "skills", skill), force);
+      console.log(`${result} ${agentRoot}/skills/${skill}`);
+    }
+    if (existsSync(REFERENCES_ROOT)) copyIfMissing(REFERENCES_ROOT, join(agentRoot, "references"), force);
+  }
+  const tools = join(root, "tools");
+  if (existsSync(TOOLS_ROOT)) {
+    for (const group of ["clis", "integrations"]) {
+      if (existsSync(join(TOOLS_ROOT, group))) copyIfMissing(join(TOOLS_ROOT, group), join(tools, group), force);
+    }
+  }
+  const stateDir = join(root, ".maggie");
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(join(stateDir, "install.json"), JSON.stringify({ version: "0.1.0", agents: roots.map((item) => item.slice(root.length + 1)), skills, installed_at: new Date().toISOString() }, null, 2) + "\n");
+  console.log(`Maggie installed in ${root}`);
+  console.log("Run `maggie doctor --project .` before using mutating workflows.");
+}
+
+function list() {
+  for (const skill of SKILL_NAMES) console.log(skill);
+}
+
+function doctor(args) {
+  const root = projectRoot(args);
+  const checks = [
+    ["project", existsSync(root)],
+    ["bootstrap-state", existsSync(join(root, ".maggie", "bootstrap-state.json"))],
+    ["codex-skills", existsSync(join(root, ".agents", "skills"))],
+    ["claude-skills", existsSync(join(root, ".claude", "skills"))],
+  ];
+  for (const [name, passed] of checks) console.log(`${passed ? "PASS" : "INFO"} ${name}`);
+  const installed = [];
+  for (const agentRoot of [join(root, ".agents"), join(root, ".claude")]) {
+    for (const skill of SKILL_NAMES) if (existsSync(join(agentRoot, "skills", skill, "SKILL.md"))) installed.push(`${agentRoot}/${skill}`);
+  }
+  console.log(`INFO installed-skills=${installed.length}`);
+  console.log("INFO doctor is diagnostic; bootstrap completion remains a project decision gate.");
+}
+
+function remove(args) {
+  const root = projectRoot(args);
+  const skills = selectedSkills(args);
+  for (const agentRoot of agentRoots(args, root)) {
+    for (const skill of skills) {
+      const target = join(agentRoot, "skills", skill);
+      if (existsSync(target)) {
+        rmSync(target, { recursive: true, force: false });
+        console.log(`removed ${target}`);
+      } else console.log(`absent ${target}`);
+    }
+  }
+}
+
+const [command = "help", ...args] = process.argv.slice(2);
+try {
+  if (["help", "--help", "-h"].includes(command)) usage();
+  else if (command === "list") list();
+  else if (command === "init" || command === "install") install(args);
+  else if (command === "doctor") doctor(args);
+  else if (command === "remove") remove(args);
+  else throw new Error(`unknown command: ${command}`);
+} catch (error) {
+  console.error(`maggie: ${error.message}`);
+  process.exitCode = 1;
+}

package/bundled-references/ai-native-blog-contract.md

@@ -0,0 +1,310 @@
+# Maggie AI-Native Blog Application Contract
+
+This contract describes the complete application surface for a Maggie-powered
+blog. It fixes the content, operations, and SEO semantics while leaving visual
+design and component composition to the implementing agent.
+
+## Public information architecture
+
+The default route map is:
+
+```text
+/blog                         published post index
+/blog/[slug]                  post detail
+/topics                       topic index
+/topics/[topic-slug]          topic landing page and post grid
+/authors/[author-slug]        authorship page when author pages are enabled
+/about                        optional organisation/EEAT page
+/sitemap.xml                  sitemap index or single sitemap
+/sitemap-posts-[part].xml     post sitemap parts when required
+/robots.txt                   crawl rules and sitemap reference
+```
+
+### Blog index
+
+The blog index should contain, in an accessible and crawlable order:
+
+1. page title and concise description;
+2. optional featured or latest post block;
+3. hot-topic navigation using real topic URLs;
+4. blog grid/list with title, excerpt, date, author, image alt text, and
+   normal anchor links;
+5. stable pagination with self-canonical pages and no indexable duplicate
+   query URLs;
+6. useful FAQ section only when questions and answers are maintained in the
+   content model;
+7. a configured CTA with explicit attribution.
+
+### Post detail
+
+Each published post must render:
+
+- title, excerpt, canonical URL, language, and visible publication date;
+- author name, author profile link, credentials or organisation context when
+  available, and source attribution;
+- modified date only when it represents a real content revision;
+- readable content with one `h1`, logical `h2`/`h3` headings, table of contents
+  when useful, internal links, related topics, and related posts;
+- cover image with dimensions and meaningful alt text;
+- Article/BlogPosting JSON-LD matching the visible page;
+- FAQ section only when the FAQ items are visible and maintained;
+- CTA selected by policy, with UTM attribution generated from known values only;
+- no draft, queue, internal note, or private project context.
+
+### Topic landing page
+
+Each indexable topic page must have:
+
+- unique topic title and useful topic description;
+- a stable topic slug and canonical URL;
+- a crawlable post grid filtered by `published` status;
+- pagination when the list exceeds the configured page size;
+- optional topic FAQ with visible answers and FAQ schema only when eligible;
+- related topics and one configured CTA where relevant;
+- no thin page created solely because a tag exists.
+
+Do not create indexable topic pages until the topic has a description and a
+minimum configured number of published posts, unless the user explicitly
+approves an exception.
+
+## Stable domain model
+
+```ts
+type PublishStatus = "draft" | "review" | "approved" | "published" | "archived";
+
+type Author = {
+  id: string;
+  slug: string;
+  name: string;
+  jobTitle?: string;
+  organisation?: string;
+  bio?: string;
+  profileUrl?: string;
+  sameAs?: string[];
+  avatarUrl?: string;
+  credentials?: string[];
+};
+
+type Topic = {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  status: "draft" | "published" | "archived";
+  seoTitle?: string;
+  seoDescription?: string;
+  faqIds: string[];
+  minimumPublishedPosts: number;
+};
+
+type FaqItem = {
+  id: string;
+  question: string;
+  answerMarkdown: string;
+  sortOrder: number;
+  status: "draft" | "published";
+};
+
+type Cta = {
+  id: string;
+  label: string;
+  url: string;
+  placement: "blog_index" | "post" | "topic" | "footer";
+  status: "draft" | "active" | "archived";
+  trackingKey?: string;
+};
+
+type SeoSnapshot = {
+  title: string;
+  description: string;
+  canonicalUrl: string;
+  robots: "index,follow" | "noindex,follow" | "noindex,nofollow";
+  ogType: "website" | "article";
+  ogImageUrl?: string;
+  twitterCard: "summary" | "summary_large_image";
+  jsonLdType: "Article" | "BlogPosting" | "CollectionPage" | "FAQPage";
+};
+
+type BlogReport = {
+  id: string;
+  runType: "technical_seo" | "content_quality" | "visibility" | "analytics";
+  status: "queued" | "running" | "completed" | "failed";
+  startedAt?: string;
+  completedAt?: string;
+  summary: Record<string, unknown>;
+  findings: Array<{
+    severity: "error" | "warning" | "info";
+    code: string;
+    url?: string;
+    message: string;
+  }>;
+};
+```
+
+Extend the [canonical post model](blog-data-contract.md) with `authorIds`,
+`topicIds`, `faqIds`, `ctaId`, `seo`, and `contentQuality` rather than putting
+these fields into an untyped metadata blob.
+
+## Maggie Ops dashboard
+
+The operations dashboard is private, authenticated, and never included in the
+public sitemap or robots allowlist:
+
+```text
+/ops                         health summary and pending actions
+/ops/posts                   filterable post inventory
+/ops/posts/new               create draft
+/ops/posts/[id]/edit         edit metadata/content with validation
+/ops/posts/[id]/preview      preview draft without indexing
+/ops/topics                  topic and FAQ management
+/ops/sitemap                 sitemap source, matching history, and eligibility
+/ops/reports                 technical SEO, content, visibility, analytics reports
+/ops/settings/site           origin, locale, timezone, author defaults, CTA defaults
+/ops/settings/integrations   AI CMO key status, API Pull, GSC, and GA4 settings
+```
+
+Dashboard actions must be explicit and auditable:
+
+| Action | Required state | External write |
+|---|---|---:|
+| Save draft | authenticated editor | no |
+| Approve post | review-ready post and editor approval | no |
+| Publish post | approved post and publishing permission | yes/public |
+| Match sitemap | completed bootstrap and configured source | AI CMO API |
+| Queue rewrite | matched asset and rewrite policy | AI CMO API |
+| Sync API Pull | server key and source mapping | AI CMO API |
+| Run report | configured target/property | provider/API varies |
+| Change integration | owner/admin permission | yes |
+
+Every mutation records actor, timestamp, previous state, new state, reason,
+and correlation/idempotency key. The dashboard should show a dry-run preview
+before queueing, publishing, changing sitemap sources, or changing integration
+settings.
+
+### Ops API boundary
+
+Keep the browser UI thin. All reads and mutations go through authenticated
+server-side routes with typed request/response objects:
+
+```text
+GET    /api/ops/summary
+GET    /api/ops/posts?status=&topic=&page=
+POST   /api/ops/posts
+GET    /api/ops/posts/[id]
+PATCH  /api/ops/posts/[id]
+POST   /api/ops/posts/[id]/preview
+POST   /api/ops/posts/[id]/approve
+POST   /api/ops/posts/[id]/publish
+GET    /api/ops/topics
+POST   /api/ops/topics
+PATCH  /api/ops/topics/[id]
+GET    /api/ops/sitemap/runs
+POST   /api/ops/sitemap/match
+POST   /api/ops/sitemap/auto-detect
+GET    /api/ops/reports?type=&status=
+POST   /api/ops/reports
+GET    /api/ops/settings
+PATCH  /api/ops/settings/site
+PATCH  /api/ops/settings/integrations
+```
+
+Every route must perform session authentication, role authorization, input
+schema validation, and state-transition validation. Do not expose raw database
+queries or the AI CMO key to the browser. Return a correlation ID with errors
+so an Ops user can reconcile a failed action without seeing secret values.
+
+The post editor must validate title, slug, excerpt, language, author, topics,
+publication status, canonical URL, cover image/alt text, and SEO fields before
+save. A preview uses `noindex` and the same renderer as the public post; it is
+not a second content implementation.
+
+### Ops dashboard summary
+
+`GET /api/ops/summary` should expose only bounded operational facts:
+
+```ts
+type OpsSummary = {
+  bootstrap: "complete" | "incomplete";
+  content: { published: number; drafts: number; review: number; failedSyncs: number };
+  sitemap: { lastRunAt?: string; matched: number; eligible: number; unmatched: number };
+  reports: { openErrors: number; lastTechnicalSeoRunAt?: string };
+  integrations: { aiCmo: "disabled" | "configured" | "verified" | "error"; gsc: string; ga4: string };
+};
+```
+
+Counts must be calculated from the same repositories used by the public
+routes. Do not use stale client counters to decide whether a post is eligible
+for publication or rewrite.
+
+## Configuration boundary
+
+Keep non-secret configuration typed and reviewable:
+
+```ts
+type BlogConfig = {
+  site: {
+    name: string;
+    baseUrl: string;
+    locale: string;
+    timezone: string;
+    blogPath: string;
+    postsPerPage: number;
+    topicMinimumPosts: number;
+  };
+  defaults: {
+    authorId?: string;
+    ctaId?: string;
+    language: string;
+    robotsPolicy: "index,follow" | "noindex,follow";
+  };
+  integrations: {
+    aiCmo: { enabled: boolean; baseUrl: string; apiKeyEnv: string; syncMode: "manual" | "scheduled" };
+    gsc: { enabled: boolean; verificationMode?: "html" | "dns" };
+    ga4: { enabled: boolean; measurementIdEnv?: string; consentRequired: boolean };
+  };
+  publishing: {
+    requireApproval: boolean;
+    allowScheduledPublish: boolean;
+    allowAutoRewritePublish: boolean;
+  };
+};
+```
+
+Secret values stay in runtime environment variables. The dashboard may show
+configured/missing/verified status, but never the key or token value.
+
+## Backend and SEO invariants
+
+- Public reads select `status = published` and valid `publishedAt` in one
+  repository function; templates must not implement their own filtering.
+- Post, topic, FAQ, author, CTA, and report IDs are stable and never derived
+  from mutable display text after publication.
+- Every public URL has one canonical owner. Slug changes create redirects and
+  never silently create a second page.
+- Preview, draft, review, archived, ops, and report URLs are `noindex` and
+  excluded from sitemap output.
+- The sitemap is generated from the same publication query used by the public
+  list, not from a separate hand-maintained URL array.
+- Metadata and JSON-LD are generated from validated domain objects, not from
+  free-form agent prose.
+- Build and report failures preserve the last known-good public output.
+- API Pull, GSC, and GA4 integrations are optional; missing credentials must
+  produce a visible disabled/unverified state, not a broken build.
+
+## Implementation order
+
+Generate and verify the application in this order:
+
+1. typed config and environment validation;
+2. database migrations and repository functions;
+3. post/topic/author/FAQ/CTA schemas and seed fixtures;
+4. public rendering and metadata helpers;
+5. sitemap/robots generation from the publication query;
+6. authenticated Ops API and dashboard screens;
+7. API Pull adapter, sitemap matching, and state reporting;
+8. reports, GSC/GA4 readback, and scheduled jobs;
+9. integration, route, metadata, and migration tests.
+
+Do not build the dashboard against mock objects after step 2. Fixtures are for
+tests and empty-state UI only; production reads must use the validated
+repository boundary.

package/bundled-references/blog-data-contract.md

@@ -0,0 +1,146 @@
+# Maggie Blog Data Contract
+
+This contract is the stable backend boundary for every Maggie framework
+template. UI components may differ, but adapters should normalize all content
+to this model before rendering.
+
+## Canonical post model
+
+```ts
+type PostStatus = "draft" | "review" | "approved" | "scheduled" | "published" | "archived";
+
+type BlogPost = {
+  id: string;                    // local stable id
+  source: "local" | "api-pull" | "cms" | "manual";
+  sourceId?: string;             // remote content_id or provider id
+  slug: string;                  // unique public identity
+  title: string;
+  excerpt: string;
+  contentMarkdown?: string;
+  contentHtml?: string;
+  canonicalUrl: string;
+  coverImageUrl?: string;
+  coverImageAlt?: string;
+  authorName?: string;
+  authorUrl?: string;
+  language: string;
+  tags: string[];
+  status: PostStatus;
+  publishedAt?: string;          // ISO-8601 UTC
+  updatedAt?: string;            // ISO-8601 UTC
+  createdAt: string;             // ISO-8601 UTC
+  contentHash?: string;
+};
+```
+
+Required invariants:
+
+- `slug` is unique and does not change after publication without a redirect.
+- `status = published` and a valid `publishedAt` are both required for a
+  public route, list item, sitemap entry, or Article JSON-LD record.
+- `canonicalUrl` is absolute, uses the configured site origin, and has no
+  tracking query parameters.
+- Store Markdown and/or sanitized HTML, never unsanitized remote HTML.
+- Keep remote `sourceId` separate from local `id`; neither may be inferred from
+  a mutable title.
+- Dates are serialized as ISO-8601 UTC and displayed using the chosen locale.
+
+## SQLite reference schema
+
+The Astro starter additionally includes migration tables for external CMS
+imports: `wp_migrations`, `wp_import_items`, `wp_terms`, `media_assets`,
+`post_media`, and `redirects`. A WordPress source identity is stored as
+`source = 'cms'` and `source_id = 'wordpress:<id>'` so it remains compatible
+with the canonical post source enum while remaining unique and rerunnable.
+
+This is the default for a new, small single-instance project. Use the same
+logical fields with Postgres or another engine when the deployment requires it.
+
+```sql
+CREATE TABLE posts (
+  id TEXT PRIMARY KEY,
+  source TEXT NOT NULL CHECK (source IN ('local', 'api-pull', 'cms', 'manual')),
+  source_id TEXT,
+  slug TEXT NOT NULL UNIQUE,
+  title TEXT NOT NULL,
+  excerpt TEXT NOT NULL DEFAULT '',
+  content_markdown TEXT,
+  content_html TEXT,
+  canonical_url TEXT NOT NULL UNIQUE,
+  cover_image_url TEXT,
+  cover_image_alt TEXT,
+  author_name TEXT,
+  author_url TEXT,
+  language TEXT NOT NULL DEFAULT 'en',
+  status TEXT NOT NULL DEFAULT 'draft'
+    CHECK (status IN ('draft', 'review', 'approved', 'scheduled', 'published', 'archived')),
+  published_at TEXT,
+  updated_at TEXT,
+  created_at TEXT NOT NULL,
+  content_hash TEXT,
+  CHECK (status <> 'published' OR published_at IS NOT NULL)
+);
+
+CREATE UNIQUE INDEX posts_source_identity
+  ON posts (source, source_id)
+  WHERE source_id IS NOT NULL;
+CREATE INDEX posts_public_order
+  ON posts (status, published_at DESC, updated_at DESC);
+
+CREATE TABLE post_tags (
+  post_id TEXT NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
+  tag TEXT NOT NULL,
+  PRIMARY KEY (post_id, tag)
+);
+
+CREATE TABLE content_sync_state (
+  source TEXT PRIMARY KEY,
+  cursor TEXT,
+  etag TEXT,
+  last_success_at TEXT,
+  last_error TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE content_delivery_state (
+  post_id TEXT PRIMARY KEY REFERENCES posts(id) ON DELETE CASCADE,
+  remote_content_id TEXT,
+  remote_version TEXT,
+  delivery_status TEXT NOT NULL DEFAULT 'not_delivered'
+    CHECK (delivery_status IN ('not_delivered', 'received', 'stored', 'published', 'failed')),
+  last_reported_url TEXT,
+  last_reported_hash TEXT,
+  last_error TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE post_redirects (
+  old_slug TEXT PRIMARY KEY,
+  post_id TEXT NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL
+);
+```
+
+For a multi-instance or serverless production deployment, confirm the hosted
+database and migration strategy before using SQLite. Never silently create a
+second database beside an existing ORM or CMS database.
+
+## API Pull normalization
+
+Map the remote response at one adapter boundary:
+
+```text
+remote content_id       -> posts.source_id and content_delivery_state.remote_content_id
+remote id                -> posts.source_id when content_id is unavailable
+remote title             -> posts.title
+remote excerpt           -> posts.excerpt
+remote content_markdown  -> posts.content_markdown
+remote content_html      -> sanitize, then posts.content_html
+remote canonical_url     -> posts.canonical_url
+remote slug              -> posts.slug, never overwrite a published local slug
+remote generated_at      -> posts.updated_at
+```
+
+The adapter must validate required fields, preserve the original response for
+debugging outside public output, upsert by source identity, and only mark a
+delivery successful after local storage succeeds.

package/bundled-references/blog-implementation.md

@@ -0,0 +1,46 @@
+# Framework-Neutral Blog Implementation Contract
+
+This is the minimum complete blog surface. Framework templates may map these
+routes differently, but must preserve their behaviour.
+
+## Public surface
+
+| Surface | Requirement |
+|---|---|
+| Posts index | Crawlable links, title, excerpt, published date, pagination or bounded feed |
+| Post detail | Stable slug, 404 for missing/unpublished content, canonical URL |
+| Robots | Allow public posts and reference the sitemap |
+| Sitemap | Published posts only, absolute canonical URLs, `lastmod` when known |
+| Metadata | Title, description, canonical, OG, Twitter, Article JSON-LD |
+| Analytics | GA4 only when configured and consent policy permits |
+| GSC | Verification path or documented DNS verification |
+
+## Data rules
+
+- `slug` is unique and immutable after publication unless a redirect is created.
+- `publishedAt` controls sitemap/index inclusion.
+- `updatedAt` is not a substitute for publication state.
+- `canonicalUrl` wins over inferred request host when configured.
+- Untrusted HTML is sanitized before rendering.
+
+## Technical SEO acceptance
+
+- one canonical per post;
+- no indexable duplicate query URLs;
+- server output contains the post title and primary content;
+- one `h1` per post;
+- images have dimensions or stable layout reservation and alt text;
+- internal links use normal anchors;
+- sitemap and robots return 200 with the correct content type.
+
+## GEO/AI discoverability acceptance
+
+The implementation should make the same facts available to humans and crawlers:
+
+- clear author, organisation, date, and source attribution;
+- concise answer-first opening paragraphs;
+- descriptive headings and stable URLs;
+- Article JSON-LD matching visible content;
+- no robots rule that accidentally blocks major search crawlers;
+- no claim that crawler access guarantees AI citations or rankings.
+