@topy-ai/maggie 0.1.0

package/bundled-tools/clis/maggie_clone.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Plan collision-safe Maggie clone namespaces without touching a project."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+from pathlib import Path
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+
+def normalized(url: str) -> str:
+    value = urlsplit(url.strip())
+    if value.scheme not in {"http", "https"} or not value.netloc:
+        raise ValueError(f"invalid URL: {url}")
+    host = value.hostname.lower() if value.hostname else ""
+    port = value.port
+    default = (value.scheme == "http" and port == 80) or (value.scheme == "https" and port == 443)
+    authority = host if not port or default else f"{host}:{port}"
+    path = value.path or "/"
+    if path != "/":
+        path = "/" + "/".join(part for part in path.split("/") if part)
+    query = urlencode(sorted(parse_qsl(value.query, keep_blank_values=True)))
+    return urlunsplit((value.scheme, authority, path, query, value.fragment))
+
+
+def key_part(value: str, fallback: str) -> str:
+    cleaned = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return cleaned[:48] or fallback
+
+
+def plan(urls: list[str], project: Path) -> list[dict[str, str]]:
+    result = []
+    seen: set[tuple[str, str]] = set()
+    for raw in urls:
+        url = normalized(raw)
+        parts = urlsplit(url)
+        origin = f"{parts.scheme}://{parts.netloc}"
+        path_state = parts.path + (f"?{parts.query}" if parts.query else "") + (f"#{parts.fragment}" if parts.fragment else "")
+        site_hash = hashlib.sha256(origin.encode()).hexdigest()[:8]
+        page_hash = hashlib.sha256(path_state.encode()).hexdigest()[:8]
+        identity = (origin, path_state)
+        if identity in seen:
+            raise ValueError(f"duplicate target after normalization: {raw}")
+        seen.add(identity)
+        site_key = f"{key_part(parts.netloc, 'site')}-{site_hash}"
+        segments = [part for part in parts.path.split("/") if part]
+        page_slug = "-".join(key_part(part, "page") for part in segments) if segments else "root"
+        page_key = f"{page_slug[:48]}-{page_hash}"
+        route = parts.path or "/"
+        result.append({
+            "source_url": url,
+            "origin": origin,
+            "destination_route": route,
+            "site_key": site_key,
+            "page_key": page_key,
+            "artifact_root": str(project / "docs/research" / site_key / page_key),
+            "screenshot_root": str(project / "docs/design-references" / site_key / page_key),
+            "component_root": str(project / "src/components/sites" / site_key / page_key),
+            "asset_root": str(project / "public/sites" / site_key / page_key),
+        })
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    command = sub.add_parser("plan", help="emit a read-only clone output plan")
+    command.add_argument("urls", nargs="+", help="authorized target URLs")
+    command.add_argument("--project", type=Path, default=Path.cwd())
+    args = parser.parse_args()
+    try:
+        print(json.dumps({"project_root": str(args.project.resolve()), "targets": plan(args.urls, args.project.resolve())}, indent=2))
+    except ValueError as error:
+        parser.error(str(error))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/site_audit.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Small dependency-free SEO/GEO smoke audit for a public site."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from html.parser import HTMLParser
+from urllib.parse import urljoin, urlparse
+from urllib.request import Request, urlopen
+
+
+class PageParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.title = ""
+        self.h1 = 0
+        self.canonical = ""
+        self.jsonld = 0
+        self.anchors = 0
+        self.in_title = False
+
+    def handle_starttag(self, tag, attrs):
+        data = dict(attrs)
+        if tag == "title":
+            self.in_title = True
+        elif tag == "h1":
+            self.h1 += 1
+        elif tag == "link" and data.get("rel", "").lower() == "canonical":
+            self.canonical = data.get("href", "")
+        elif tag == "script" and data.get("type") == "application/ld+json":
+            self.jsonld += 1
+        elif tag == "a" and data.get("href"):
+            self.anchors += 1
+
+    def handle_endtag(self, tag):
+        if tag == "title":
+            self.in_title = False
+
+    def handle_data(self, data):
+        if self.in_title:
+            self.title += data.strip()
+
+
+def fetch(url: str) -> tuple[int, str, str]:
+    request = Request(url, headers={"User-Agent": "AI-CMO-Skills-Audit/0.1"})
+    with urlopen(request, timeout=15) as response:
+        body = response.read(2_000_000).decode("utf-8", "replace")
+        return response.status, response.headers.get_content_type(), body
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("url")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args()
+    base = args.url.rstrip("/")
+    checks = {}
+    try:
+        status, content_type, html = fetch(base)
+        page = PageParser()
+        page.feed(html)
+        checks["homepage"] = {"status": status, "content_type": content_type}
+        checks["title"] = {"ok": bool(page.title), "value": page.title}
+        checks["h1"] = {"ok": page.h1 == 1, "count": page.h1}
+        checks["canonical"] = {"ok": bool(page.canonical), "value": page.canonical}
+        checks["article_jsonld"] = {"ok": page.jsonld > 0, "count": page.jsonld}
+        checks["crawlable_links"] = {"ok": page.anchors > 0, "count": page.anchors}
+    except Exception as exc:
+        checks["homepage"] = {"ok": False, "error": type(exc).__name__}
+
+    for name, path in (("robots", "/robots.txt"), ("sitemap", "/sitemap.xml")):
+        try:
+            status, content_type, body = fetch(urljoin(base + "/", path.lstrip("/")))
+            checks[name] = {
+                "ok": status == 200,
+                "status": status,
+                "content_type": content_type,
+                "mentions_sitemap": "sitemap" in body.lower() if name == "robots" else None,
+                "url_count": len(re.findall(r"<loc>.*?</loc>", body, re.I | re.S)) if name == "sitemap" else None,
+            }
+        except Exception as exc:
+            checks[name] = {"ok": False, "error": type(exc).__name__}
+
+    result = {"url": base, "checks": checks, "passed": all(v.get("ok", False) for v in checks.values())}
+    if args.as_json:
+        print(json.dumps(result, indent=2))
+    else:
+        for name, value in checks.items():
+            print(f"{'PASS' if value.get('ok') else 'FAIL'} {name}: {value}")
+        print("RESULT:", "PASS" if result["passed"] else "FAIL")
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

package/bundled-tools/integrations/analytics.md

@@ -0,0 +1,34 @@
+# GA4 and Google Search Console
+
+## GA4
+
+Use the host framework's supported Google tag integration. The minimum
+configuration is:
+
+```text
+NEXT_PUBLIC_GA4_MEASUREMENT_ID=G-...
+GA4_ENABLED=true
+```
+
+For another framework, use equivalent names in `.env.example`. The integration
+must be disabled when the measurement ID is absent or consent is not granted.
+Do not send post body, API keys, or unnecessary personal data as event params.
+
+Recommended events: `page_view` (automatic), `blog_post_view`, and an explicit
+conversion event only when the host project defines one.
+
+## GSC
+
+Prefer DNS verification for production. If HTML verification is needed, use a
+public token environment variable and render the exact verification tag. OAuth
+refresh tokens and service-account JSON stay server-side and out of the repo.
+
+```text
+GSC_SITE_URL=https://example.com
+GSC_VERIFICATION_TOKEN=replace-me
+```
+
+GSC data is read-only in this starter. Any query, page, or indexing report must
+show its date window and property so an agent does not confuse an empty result
+with a failed connection.
+

package/bundled-tools/integrations/maggie-api-pull.md

@@ -0,0 +1,72 @@
+# Maggie API-Pull Integration
+
+The public edge is `https://api.cmo.so`. The API key is sent as:
+
+```http
+Authorization: Bearer aicmo_...
+```
+
+Never expose this key in browser JavaScript, client bundles, logs, screenshots,
+or public repositories. Keep polling server-side or in a protected job.
+
+## Lifecycle
+
+```text
+GET /whoami
+  -> POST /sitemap/match or /sitemap/auto-detect
+  -> GET /sitemap/matching-history
+  -> POST /rewrite/queue (optional explicit rewrite)
+  -> GET /rewrite/queue
+  -> GET /posts and GET /updates on a schedule
+  -> upsert local content and publish according to local approval policy
+  -> POST /content-tracking/report-state
+  -> GET /rewrite/history/{content_id}
+```
+
+## Project context synchronization
+
+`GET /project-context` returns the sanitized, read-only context for the API
+key's AI CMO project. The key is the scope; clients must not accept a project
+id from a browser or public request.
+
+The response includes brand, product/service positioning, audience, region,
+brand voice, site URL, and the structured project CTA. It deliberately omits
+team data, uploads, testimonials, market research, and internal workflow state.
+Use the response `ETag` with `If-None-Match` for scheduled syncs, and write the
+result to a local generated file rather than modifying source-of-truth files by
+hand. Map `project.cta.default_url` and `project.cta.other_urls` into
+`conversion.ctas.default` and `conversion.ctas.additional` while preserving
+the original payload for forwards compatibility.
+
+## Endpoints
+
+| Endpoint | Use | Key |
+|---|---|---|
+| `GET /whoami` | Resolve domain and capabilities | secret or publishable |
+| `GET /project-context` | Sync sanitized project, brand voice and CTA context | secret |
+| `GET /posts` | Pull one new post | secret |
+| `GET /updates` | Pull one rewrite | secret |
+| `GET /history` | Recover delivered posts | secret |
+| `GET /rewrite-policy` | Read rewrite policy | secret |
+| `POST /rewrite-policy` | Set auto/manual policy | secret |
+| `POST /sitemap/match` | Match supplied sitemap | secret |
+| `POST /sitemap/auto-detect` | Discover and match sitemap | secret |
+| `GET /sitemap/matching-history` | Inspect prior runs | publishable |
+| `POST /rewrite/queue` | Generate one rewrite for a matched asset | secret |
+| `GET /rewrite/queue` | Inspect cached picks and pending delivery | publishable |
+| `GET /rewrite/history/{content_id}` | Inspect rewrite delivery attempts | publishable |
+| `POST /content-tracking/report-state` | Report local publication state | secret |
+| `POST /content-tracking/report-state/batch` | Report bounded inventory batch | secret |
+
+## Adapter requirements
+
+- Store remote `content_id`, `version`, `slug`, and `canonical_url` locally.
+- Upsert new posts idempotently. A retry must not create a duplicate slug.
+- On rewrite, update the existing record at the same canonical URL. Do not
+  replace the slug unless the API contract explicitly changes.
+- Treat an empty `/posts` or `/updates` response as normal, not an error.
+- Back off on 429/5xx and include an idempotency key where supported.
+- Do not ack a local update until the new body is stored and the local publish
+  result is known.
+- Use `report-state` for observed URL/status/hash so the tracking record can be
+  reconciled later.

package/bundled-tools/integrations/maggie-project-context.md

@@ -0,0 +1,62 @@
+# Maggie Project Context Adapter
+
+This adapter connects a host project to the AI CMO source of truth without
+requiring the host project to know the AI CMO database schema.
+
+## Request
+
+```http
+GET https://api.cmo.so/project-context
+Authorization: Bearer aicmo_...
+If-None-Match: "previous-etag"
+```
+
+The API key scopes the request to one domain, AI CMO workspace and Project. The
+request must run server-side. A `304` means the generated local context remains
+current.
+
+## Safe response usage
+
+Use these response fields to generate or refresh local files:
+
+```text
+project.brand/title/description
+project.products_services/usp
+project.target_problem/target_audience/target_region
+project.keywords/industries
+project.cta
+brand_voice
+site.domain/base_url
+sync.updated_at
+```
+
+Keep `context` intact for forward compatibility, but do not expose it directly
+to browsers unless the host project has explicitly reviewed every field.
+
+## CTA normalization
+
+The source CTA can contain `default_url` and `other_urls`, where each item may
+contain `cta_url`, `url`, `href`, text, target keyword, priority, and additional
+metadata. Preserve all metadata and normalize only the local view:
+
+```json
+{
+  "conversion": {
+    "ctas": {
+      "default": { "cta_url": "https://example.com/start" },
+      "additional": []
+    }
+  }
+}
+```
+
+Never invent a fallback CTA when the Project has no approved CTA. Ask for an
+explicit destination or keep the content in preview mode.
+
+## Refresh policy
+
+- manual sync before bootstrap or a content strategy change;
+- scheduled sync with ETag revalidation after that;
+- show changed fields before updating public copy or links;
+- record `project_id`, `ai_cmo_id`, `updated_at`, ETag, timestamp and result;
+- never commit `generated/ai-cmo-context.json` if it contains private context.

package/bundled-tools/integrations/maggie-seo-audit.md

@@ -0,0 +1,16 @@
+# Maggie SEO Audit Integration
+
+Use the deterministic local audit first, then the paid/server-side audit when
+the user has access to the full AI CMO feature.
+
+## Audit layers
+
+1. Local: HTTP status, robots, sitemap, canonical, metadata, headings, links,
+   JSON-LD, image alt text and server-rendered post paths.
+2. Provider: performance, accessibility, best practices and SEO diagnostics.
+3. AI readiness: extractability, author/freshness/evidence signals, crawler
+   access and public machine-readable context.
+
+Provider runs should be asynchronous, cached, bounded by entitlement, and
+reported with `job_id`, `audit_id`, `data_through`, and issue severity. A
+provider outage must not be presented as a site failure.

package/bundled-tools/integrations/maggie-skills-api.md

@@ -0,0 +1,76 @@
+# Maggie Skills API (versioned)
+
+This is the additive API for the Skills workflow. It does not replace the
+legacy API Pull contract in [maggie-api-pull.md](./maggie-api-pull.md).
+
+The legacy guide remains authoritative for the existing root endpoints. New
+Skills integrations should use this namespace for lifecycle operations; do not
+rewrite existing `/posts`, `/updates`, or `/rewrite/queue` adapters.
+
+Base URL:
+
+```text
+https://api.cmo.so/api/v1/maggie
+```
+
+Authentication is server-side only:
+
+```http
+Authorization: Bearer aicmo_...
+```
+
+The edge is only an API-key proxy. Data and mutations are handled by TOPY and
+the shared MySQL database. Never put the key in browser code or a public build.
+
+## Contract discovery
+
+Use `GET /api-version` to identify the additive contract and
+`GET /capabilities` to feature-detect optional capabilities. The current
+published OpenAPI contract is the source of truth for method details. Read-only
+operations do not consume AI quota. Operations that may consume quota return
+the `X-Quota-*` headers; callers must preserve and report them.
+
+## Endpoint map
+
+| Area | Endpoints |
+|---|---|
+| Version and usage | `GET /api-version`, `GET /capabilities`, `GET /entitlements`, `GET /usage`, `GET /usage/events`, `POST /usage/events` |
+| Pull runs | `GET/POST /pull/runs`, `GET /pull/runs/{record_id}`, `GET /pull/runs/{record_id}/items` |
+| Content assets | `GET /content-assets`, `GET/POST /content-assets/backfill`, `GET /content-assets/{record_id}`, `GET/PATCH /content-assets/{record_id}/identity`, `GET /content-assets/{record_id}/versions` |
+| Sitemap sources | `GET/POST /sitemap/sources`, `GET/PATCH/DELETE /sitemap/sources/{record_id}`, plus the same `GET/POST` and `GET/PATCH/DELETE` plural `/sitemaps/sources` routes |
+| Sitemap runs | `GET/POST /sitemap/runs`, `GET /sitemap/runs/{record_id}`, `GET /sitemap/runs/{record_id}/cancel`, plus the same `GET/POST`, `GET`, and `GET` cancel plural `/sitemaps/runs` routes |
+| Sitemap schedules | `GET/POST /sitemap/schedules`, `GET/POST /sitemaps/schedules` (the current contract has no item route for schedules) |
+| Rewrite jobs | `GET/POST /rewrite/jobs`, `GET/POST /rewrite/jobs/batch`, `GET /rewrite/jobs/{record_id}`, `GET /rewrite/jobs/{record_id}/preview|approve|reject|cancel|retry`, `GET /rewrite/jobs/{record_id}/versions` |
+| SEO | `GET/POST /seo/audits`, `GET /seo/audits/{record_id}`, `GET/POST /seo/insights` |
+| Visibility | `GET/POST /visibility/runs`, `GET /visibility/runs/{record_id}`, `GET/POST /visibility/prompts`, `GET/POST /visibility/competitors` |
+| Projects and sites | `GET /projects`, `GET /projects/{record_id}`, `GET /projects/{record_id}/context|ctas`, `GET /sites`, `GET /sites/{record_id}`, `GET /sites/{record_id}/context|settings`, `PATCH /sites/{record_id}/settings` |
+| Reports | `GET/POST /reports`, `GET /reports/{record_id}`, `GET/POST /reports/{record_id}/deliver`, `GET /reports/{record_id}/deliveries` |
+| Jobs | `GET/POST /scheduled-jobs`, `GET/POST /jobs`, `GET /jobs/{record_id}`, `GET/POST /jobs/{record_id}/run` |
+| Social | `GET/POST /social/drafts`, `GET /social/drafts/{record_id}`, `GET /social/drafts/{record_id}/approve|reject|schedule|publish`, `GET/POST /social/accounts`, `GET/POST /social/calendars`, `GET/POST /social/schedules`, `GET/POST /social/metrics`, `GET/POST /social/publish`, `GET /social/publish/{record_id}` |
+| Deployments | `GET /deployment/providers`, `GET/POST /deployment/validate`, `GET/POST /deployment/registrations`, `GET /deployment/registrations/{record_id}`, `GET /deployment/registrations/{record_id}/report`; plural routes: `GET /deployments/providers`, `GET/POST /deployments/validate`, `GET/POST /deployments`, `GET /deployments/{record_id}/report` |
+
+`{record_id}` is the resource identifier returned by the API. Treat status and
+response fields as forward-compatible; unknown fields must be preserved.
+
+## Workflow
+
+```text
+api-version/capabilities
+  -> pull run or content-assets backfill
+  -> sitemap source/run
+  -> rewrite job preview
+  -> approve/reject/cancel
+  -> local publish and report-state (legacy endpoint)
+  -> usage/history/readback
+```
+
+Use `Idempotency-Key` for every mutation that can be retried. Do not treat a
+queued response as delivered or published. Keep the legacy `/posts`,
+`/updates`, `/project-context`, `/sitemap/match`, `/rewrite/queue`, and
+`/content-tracking/report-state` calls unchanged when using the established
+API Pull adapter.
+
+For legacy adapter discovery, `GET https://api.cmo.so/whoami` remains available
+with the original response contract. It is intentionally separate from the
+versioned Skills namespace; new clients should discover the versioned contract
+with `/api-version` and `/capabilities`.

package/bundled-tools/integrations/maggie-social-share.md

@@ -0,0 +1,23 @@
+# Maggie Social Share Integration
+
+Social Share consumes approved AI CMO content assets and produces channel
+derivatives. It must retain `source_content_id`, canonical URL, Project CTA,
+voice/tone, approval state, provider post ID, and publication attempts.
+
+## Provider contract
+
+Each channel adapter declares OAuth scopes, supported formats, max lengths,
+media requirements, publish/delete/republish support, retry classification and
+idempotency behavior. Start with LinkedIn and Facebook; do not claim support for
+a provider until its adapter and production credentials are verified.
+
+## State machine
+
+```text
+draft -> approved -> scheduled -> publishing -> published
+                         \-> cancelled
+publishing -> failed -> retrying -> published | failed
+```
+
+Publishing requires a paid entitlement, active connection and explicit
+approval. A generated social draft is never proof that a provider post exists.

package/bundled-tools/integrations/maggie-visibility.md

@@ -0,0 +1,22 @@
+# Maggie Visibility Integration
+
+This is the contract for AI SEO/GEO visibility work. The exact public route
+availability is versioned in AI CMO's OpenAPI document; do not hard-code private
+Geo service credentials in a host project.
+
+## Required behavior
+
+- scope every request to the authenticated domain/project;
+- distinguish quick prompt checks from recurring monitoring;
+- enforce server-side feature quota and subscription entitlement;
+- record query set, provider, run time, result status, citations and source URLs;
+- report observed retrieved/cited/mentioned/recommended states separately;
+- treat provider failures as retryable operational errors, not zero visibility;
+- never claim ranking, citation or traffic improvement without measured data.
+
+## Host output
+
+The skill should produce a preview/report containing query coverage, competitor
+presence, citation/source gaps, technical blockers, and the next content action.
+It should not directly rewrite or publish content until the content workflow's
+approval state allows it.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@topy-ai/maggie",
+  "version": "0.1.0",
+  "description": "Install and manage Maggie Skills for AI coding agents",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "maggie": "bin/maggie.js"
+  },
+  "files": [
+    "bin",
+    "references",
+    "bundled-skills",
+    "bundled-references",
+    "bundled-tools"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/package-cli.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TOPY-AI-LTD/ai-cmo-skills.git",
+    "directory": "packages/maggie-cli"
+  },
+  "homepage": "https://github.com/TOPY-AI-LTD/ai-cmo-skills"
+}