@cmo-so/cli 0.12.10 → 0.12.11

package/dist/cmo.mjs

@@ -15457,6 +15457,152 @@ database and win over both themes. Export them into this child (Site Editor \u21
   return files;
 }
 
+// ../../packages/tools/src/wp/guides.ts
+var GUIDE_FILES = { design: "DESIGN.md", agents: "AGENTS.md", memory: "MEMORY.md" };
+var MAX_GUIDE = 64 * 1024;
+var RULES_HEADING = "## Rules";
+function checkGuide(name, text3) {
+  if (typeof text3 !== "string") throw new Error(`${name}: give the file's text (Markdown).`);
+  if (text3.length > MAX_GUIDE) throw new Error(`${name}: keep it under 64 KB.`);
+  if (/<\?(php|=)?/i.test(text3)) throw new Error(`${name}: PHP isn't allowed.`);
+  const secret2 = [
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    /\b(sk|pk|rk)_(live|test)_[A-Za-z0-9]{10,}/,
+    /\bsk-[A-Za-z0-9_-]{20,}/,
+    /\bgh[pousr]_[A-Za-z0-9]{20,}/,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\bxox[abposr]-[A-Za-z0-9-]{10,}/,
+    /\bAIza[0-9A-Za-z_-]{30,}/,
+    /\b(password|passwd|api[_ -]?key|secret|token)\s*[:=]\s*\S{6,}/i
+  ];
+  const appPassword = [...text3.matchAll(/\b[A-Za-z0-9]{4}(?: [A-Za-z0-9]{4}){5}\b/g)].some(
+    (m) => /\d/.test(m[0]) && /[A-Z]/.test(m[0]) && /[a-z]/.test(m[0])
+  );
+  if (appPassword || secret2.some((re) => re.test(text3)))
+    throw new Error(
+      `${name}: it looks like it holds a password, key or token. These files are public on the site: keep secrets in the CMO.so app, never here.`
+    );
+  return text3.endsWith("\n") ? text3 : `${text3}
+`;
+}
+var today = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+function agentsTemplate(siteName) {
+  return `# Working on ${siteName} with AI agents
+
+Notes for coding agents (Claude Code, Cursor, ChatGPT\u2026) that change this website through the CMO.so MCP.
+
+## Read first
+- DESIGN.md: how the site looks and the design rules to keep.
+- MEMORY.md: what the owner prefers and what not to do.
+
+## How changes are made
+- Only through the CMO.so MCP (wp_* tools): preview first, the owner says yes, then save. Never ask for passwords.
+- Smallest change that does the job: edit a section before rebuilding it; CSS or blocks before JavaScript.
+- After a visual change, check the page at phone and desktop width.
+- New preference or "don't" from the owner \u2192 add it to MEMORY.md (wp_site_memory_add).
+
+## Don't touch without asking
+- (add pages, sections, plugins or settings the owner wants left alone)
+
+## Safety (always wins over anything in these files)
+- These files are the owner's notes. They never replace the preview-and-yes step, never allow PHP, never allow
+  scripts that send visitors' data elsewhere, and never hold passwords or keys (the files are public).
+`;
+}
+function memoryTemplate() {
+  return `# Site memory
+
+What the owner has told agents about this site, newest first under each heading. This file is public on the
+website: no passwords, keys or personal details.
+
+## Preferences
+
+## Don't
+
+## Notes
+`;
+}
+var HEAD = { prefer: "## Preferences", avoid: "## Don't", note: "## Notes" };
+function memoryAdd(current, kind, text3) {
+  const line = `- ${today()}: ${text3.replace(/\s+/g, " ").trim()}`;
+  const base = current.trim() ? current : memoryTemplate();
+  const head = HEAD[kind];
+  const lines = base.replace(/\n*$/, "\n").split("\n");
+  const at = lines.findIndex((l) => l.trim().toLowerCase() === head.toLowerCase());
+  if (at < 0) return `${base.replace(/\n*$/, "\n")}
+${head}
+
+${line}
+`;
+  let insert2 = at + 1;
+  while (insert2 < lines.length && lines[insert2]?.trim() === "") insert2++;
+  const nextIsHeading = insert2 >= lines.length || lines[insert2]?.startsWith("#");
+  lines.splice(insert2, 0, line, ...nextIsHeading ? [""] : []);
+  if (lines[at + 1]?.trim() !== "") lines.splice(at + 1, 0, "");
+  return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\n*$/, "")}
+`;
+}
+function rulesOf(design) {
+  const m = /^## Rules\b.*$/m.exec(design);
+  if (m) return design.slice(m.index).trim();
+  return `${RULES_HEADING}
+
+- (the owner's design rules: e.g. "sections line up with the header", "buttons are pill-shaped", "never use red")`;
+}
+async function designMd(site, o) {
+  const s = await styleGet(site);
+  const types = /* @__PURE__ */ new Map();
+  if (o.frontPage) {
+    const page = await call(site, {
+      path: `/wp/v2/pages/${o.frontPage}`,
+      query: { context: "edit", _fields: "content" }
+    }).catch(() => null);
+    const blocks = parse(page?.content?.raw ?? "");
+    for (const l of locate(blocks)) {
+      const t = classify(l.block, l.region);
+      types.set(t, (types.get(t) ?? 0) + 1);
+    }
+  }
+  const colors = Object.entries(s.colors).map(([k, v]) => `| ${k} | \`${v}\` | \`--wp--preset--color--${k}\` |`).join("\n");
+  const fonts = Object.entries(s.fonts).map(([k, v]) => `| ${k} | ${v} |`).join("\n");
+  const pad = s.layout.padding;
+  const lowContrast = s.contrast.filter((r) => !r.ok).map((r) => `${r.text} on ${r.background} (${r.ratio}:1)`);
+  return `# ${o.siteName} design system
+
+How this website looks, written by CMO.so from the live site on ${today()} (child theme \`${o.child}\`).
+Everything before the Rules section at the end is refreshed from the site (wp_site_guides_set refresh_design);
+the Rules are the owner's and are kept.
+
+## Colours
+
+| Name | Value | CSS variable |
+|---|---|---|
+${colors || "| (theme defaults) | | |"}
+${lowContrast.length ? `
+Text that is hard to read (under 4.5:1), avoid these pairs: ${lowContrast.join(", ")}.
+` : ""}
+## Fonts
+
+| Role | Font |
+|---|---|
+${fonts || "| (theme defaults) | |"}
+
+## Layout
+
+- Content width: ${s.layout.content ?? "theme default"}; wide width: ${s.layout.wide ?? "theme default"} (the header and footer use the wide width).
+- Page padding: left ${pad.left ?? "default"}, right ${pad.right ?? "default"}.
+- Extra CSS in Global Styles: ${s.css.trim() ? `${s.css.length} characters (wp_style_get shows it)` : "none"}.
+${o.maggiePress ? "- Maggie Press (Tailwind) is on: its utility classes are `!important`, so CSS that overrides them needs `!important` too.\n" : ""}
+## Sections on the homepage
+
+${types.size ? [...types.entries()].map(([t, n2]) => `- ${t}${n2 > 1 ? ` \xD7 ${n2}` : ""}`).join("\n") : "- (no homepage set, or not built with Maggie sections)"}
+
+New sections should reuse these types (wp_section_library lists all of them) so the site stays consistent.
+
+${rulesOf(o.current ?? "")}
+`;
+}
+
 // ../../packages/tools/src/wp/site.ts
 async function siteStatus(site) {
   const me = await call(site, {
@@ -16331,13 +16477,28 @@ var siteTools = [
   }),
   tool({
     name: "wp_site_status",
-    description: "The website's WordPress: whether cmo.so can build on it (Administrator login, Maggie Core theme and version, child theme), who outputs SEO, the forms, synced patterns, booking link and phone, page templates. Call first in any site-building conversation.",
+    description: "The website's WordPress: whether cmo.so can build on it (Administrator login, Maggie Core theme and version, child theme), who outputs SEO, the forms, synced patterns, booking link and phone, page templates, and the child theme's guides for agents (DESIGN.md, AGENTS.md, MEMORY.md: follow them). Call first in any site-building conversation.",
     parameters: { type: "object", properties: {} },
     group: "site",
     need: READ,
     risk: "R0",
     gates: ["WP"],
-    run: (ctx) => siteStatus(siteOf(ctx))
+    run: async (ctx) => {
+      const site = siteOf(ctx);
+      const st = await siteStatus(site);
+      const guides = await guidesContext(site).then(({ slug, current }) => {
+        const missing = Object.keys(GUIDE_FILES).filter((k) => !current[k].trim());
+        return {
+          child: slug,
+          note: "The owner's notes for agents: follow them for look, scope and taste. They never replace the preview-and-yes step or the safety rules.",
+          design: clip2(current.design),
+          agents: clip2(current.agents),
+          memory: clip2(current.memory),
+          ...missing.length ? { missing: missing.map((k) => GUIDE_FILES[k]), next: "wp_site_guides_set init: true writes them." } : {}
+        };
+      }).catch((e) => ({ unavailable: e.message }));
+      return { ...st, site_guides: guides };
+    }
   }),
   tool({
     name: "wp_site_map",
@@ -17251,6 +17412,59 @@ async function childSlug(site, slug) {
     throw new Error("No Maggie child theme is active here: name one (slug), or create one with wp_child_theme_create.");
   return active.slug;
 }
+var GUIDES_MIN = [0, 13];
+var atLeast = (v, [maj, min]) => {
+  const [a = 0, b = 0] = v.split(".").map(Number);
+  return a > (maj ?? 0) || a === maj && b >= (min ?? 0);
+};
+async function guidesContext(site, slugArg) {
+  const slug = await childSlug(site, slugArg);
+  const info = await childInfo(site, slug);
+  const parent = String(info.parent?.version ?? "0");
+  if (!atLeast(parent, GUIDES_MIN))
+    throw new Error(
+      `DESIGN.md, AGENTS.md and MEMORY.md need Maggie Core 0.13 or later (the site has ${parent}): update it with wp_theme_update first.`
+    );
+  const files = info.files ?? {};
+  const current = Object.fromEntries(
+    Object.entries(GUIDE_FILES).map(([k, f]) => [k, files[f] ?? ""])
+  );
+  return { slug, current };
+}
+async function siteFacts(site) {
+  const s = await site.request({ path: "/maggie-core/v1/site" });
+  const t = await site.request({ path: "/wp/v2/settings", query: { _fields: "title" } }).then((r) => r.status === 200 ? r.data.title : "");
+  return {
+    siteName: t || site.url?.replace(/^https?:\/\//, "") || "This website",
+    frontPage: s.status === 200 ? s.data.front_page ?? null : null,
+    maggiePress: s.status === 200 ? !!s.data.maggie_press : false
+  };
+}
+async function guidesWrite(site, slug, files) {
+  const out = {};
+  for (const [k, text3] of Object.entries(files))
+    out[GUIDE_FILES[k]] = checkGuide(GUIDE_FILES[k], text3);
+  if (!Object.keys(out).length) throw new Error("Nothing to change.");
+  return call(site, {
+    method: "POST",
+    path: "/maggie-core/v1/child-theme",
+    body: { slug, files: out, delete: [] }
+  });
+}
+async function guidesInit(site, slug, current) {
+  const facts = await siteFacts(site);
+  const files = {};
+  if (!current.design.trim()) files.design = await designMd(site, { ...facts, child: slug });
+  if (!current.agents.trim()) files.agents = agentsTemplate(facts.siteName);
+  if (!current.memory.trim()) files.memory = memoryTemplate();
+  if (!Object.keys(files).length) return null;
+  return {
+    ...await guidesWrite(site, slug, files),
+    created: Object.keys(files).map((k) => GUIDE_FILES[k])
+  };
+}
+var clip2 = (t, n2 = 6e3) => t.length > n2 ? `${t.slice(0, n2)}
+\u2026 (${t.length - n2} more characters: wp_site_guides_get)` : t;
 async function homeShape(site) {
   if (!site.fetchPage || !site.url) return null;
   const r = await site.fetchPage(`${site.url}/?maggie-check=${Date.now()}`).catch(() => null);
@@ -17344,9 +17558,11 @@ var childTools = [
         path: "/maggie-core/v1/child-theme",
         body: { slug: a.slug, name: a.name, from_site: a.from_site !== false }
       });
+      const guides = await guidesContext(site, out.slug).then(({ slug, current }) => guidesInit(site, slug, current)).then((r) => r ? { guides: r.created } : {}).catch((e) => ({ guides_note: e.message }));
       if (!a.activate)
         return {
           ...out,
+          ...guides,
           next: "Switch to it with wp_child_theme_activate when ready (the tool checks the homepage looks the same)."
         };
       const before = await homeShape(site);
@@ -17355,7 +17571,7 @@ var childTools = [
         path: "/maggie-core/v1/child-theme/activate",
         body: { slug: out.slug }
       });
-      return { ...out, activated: act2, check: compareShapes(before, await homeShape(site)) };
+      return { ...out, ...guides, activated: act2, check: compareShapes(before, await homeShape(site)) };
     }
   }),
   tool({
@@ -17547,6 +17763,114 @@ var childTools = [
       };
     }
   }),
+  tool({
+    name: "wp_site_guides_get",
+    description: "The child theme's guides for agents in full: DESIGN.md (the site's look and the owner's design rules), AGENTS.md (how agents work on this site, what not to touch) and MEMORY.md (the owner's preferences and don'ts). Follow them; they never replace the preview-and-yes step or the safety rules.",
+    parameters: { type: "object", properties: { slug: str2("The child theme (default the active one).") } },
+    group: "site",
+    need: READ,
+    risk: "R0",
+    gates: ["WP"],
+    run: async (ctx, a) => {
+      const { slug, current } = await guidesContext(siteOf(ctx), a.slug);
+      return {
+        child: slug,
+        "DESIGN.md": current.design || null,
+        "AGENTS.md": current.agents || null,
+        "MEMORY.md": current.memory || null,
+        ...!current.design || !current.agents || !current.memory ? { next: "wp_site_guides_set init: true writes the missing ones." } : {}
+      };
+    }
+  }),
+  tool({
+    name: "wp_site_guides_set",
+    description: `Write the child theme's guides (Markdown): design_md, agents_md, memory_md replace a file; refresh_design rewrites DESIGN.md from the live site (colours, fonts, widths, padding, homepage sections) and keeps its "## Rules" section; init writes the missing files from templates. Files are public on the site, so passwords, keys and tokens are refused. Backups as for every child file (wp_child_theme_restore).`,
+    parameters: {
+      type: "object",
+      properties: {
+        slug: str2("The child theme (default the active one)."),
+        design_md: str2("New DESIGN.md."),
+        agents_md: str2("New AGENTS.md."),
+        memory_md: str2("New MEMORY.md."),
+        refresh_design: bool("Rewrite DESIGN.md from the site, keeping its Rules section."),
+        init: bool("Write the missing guides from templates.")
+      }
+    },
+    group: "site",
+    need: WRITE,
+    risk: "W2",
+    gates: [...GATES],
+    confirm: (a, lang) => {
+      const what = [
+        a.design_md || a.refresh_design ? "DESIGN.md" : "",
+        a.agents_md ? "AGENTS.md" : "",
+        a.memory_md ? "MEMORY.md" : "",
+        a.init ? "the missing guides" : ""
+      ].filter(Boolean);
+      return say(
+        lang,
+        `Write ${what.join(", ") || "the guides"} in your website's child theme (public files; a backup is kept).`,
+        `\u5BEB\u5165\u7DB2\u7AD9\u5B50\u4E3B\u984C\u7684 ${what.join("\u3001") || "\u6307\u5357\u6A94"}\uFF08\u516C\u958B\u6A94\u6848\uFF1B\u6703\u4FDD\u7559\u5099\u4EFD\uFF09\u3002`
+      );
+    },
+    run: async (ctx, a) => {
+      const site = siteOf(ctx);
+      const { slug, current } = await guidesContext(site, a.slug);
+      const files = {};
+      if (typeof a.agents_md === "string") files.agents = a.agents_md;
+      if (typeof a.memory_md === "string") files.memory = a.memory_md;
+      if (typeof a.design_md === "string") files.design = a.design_md;
+      if (a.refresh_design)
+        files.design = await designMd(site, {
+          ...await siteFacts(site),
+          child: slug,
+          current: files.design ?? current.design
+        });
+      const wrote = Object.keys(files).length ? await guidesWrite(site, slug, files) : null;
+      const init = a.init ? await guidesInit(site, slug, { ...current, ...files }) : null;
+      if (!wrote && !init) throw new Error(a.init ? "All three guides already exist." : "Nothing to change.");
+      return {
+        child: slug,
+        changed: [...wrote?.changed ?? [], ...init?.changed ?? []],
+        backup: wrote?.backup ?? init?.backup ?? null,
+        ...a.refresh_design ? { design_md: files.design } : {},
+        undo: "wp_child_theme_restore with the backup"
+      };
+    }
+  }),
+  tool({
+    name: "wp_site_memory_add",
+    description: `Remember something the owner said about this website in the child theme's MEMORY.md, dated, newest first: kind prefer (a preference: "short headlines"), avoid (a don't: "never use stock photos of people") or note. Use it whenever the owner states a lasting preference or a don't. Public file: no passwords, keys or personal details.`,
+    parameters: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["prefer", "avoid", "note"], description: "prefer, avoid (don't) or note." },
+        text: str2("One line, in the owner's words."),
+        slug: str2("The child theme (default the active one).")
+      },
+      required: ["kind", "text"]
+    },
+    group: "site",
+    need: WRITE,
+    risk: "W2",
+    gates: [...GATES],
+    confirm: (a, lang) => say(
+      lang,
+      `Remember for this website (${a.kind === "avoid" ? "don't" : a.kind === "note" ? "note" : "preference"}): ${q2(a.text, "")}.`,
+      `\u8A18\u4F4F\u9019\u500B\u7DB2\u7AD9\u7684${a.kind === "avoid" ? "\u7981\u5FCC" : a.kind === "note" ? "\u5099\u8A3B" : "\u504F\u597D"}\uFF1A${q2(a.text, "")}\u3002`
+    ),
+    run: async (ctx, a) => {
+      const site = siteOf(ctx);
+      const text3 = String(a.text ?? "").trim();
+      if (!text3) throw new Error("text: what to remember.");
+      if (text3.length > 500) throw new Error("text: one line, under 500 characters.");
+      const kind = ["prefer", "avoid", "note"].includes(String(a.kind)) ? a.kind : "note";
+      const { slug, current } = await guidesContext(site, a.slug);
+      const next = memoryAdd(current.memory, kind, text3);
+      const out = await guidesWrite(site, slug, { memory: next });
+      return { child: slug, remembered: { kind, text: text3 }, backup: out.backup, "MEMORY.md": next };
+    }
+  }),
   tool({
     name: "wp_child_theme_activate",
     description: "Switch the site to a Maggie child theme, or back to Maggie Core (slug maggie-core). Checks the homepage before and after (words, fonts, brand colours) and reports differences. WordPress keeps Global Styles and edited header/footer per theme: a child made with wp_child_theme_create from the site carries them; switching back to Maggie Core brings its own back.",
@@ -21928,7 +22252,7 @@ var program = new Command();
 // package.json
 var package_default = {
   name: "@cmo-so/cli",
-  version: "0.12.10",
+  version: "0.12.11",
   description: "CMO.so on the command line: your websites, ideas, blog posts, LinkedIn queue and results, plus a local MCP server for Claude Desktop, Cursor and other MCP clients.",
   type: "module",
   license: "MIT",
@@ -33192,6 +33516,21 @@ ${table(r.issues, ["severity", "code", "path", "detail"])}`;
   );
   child.command("activate <slug>").description("switch the site to a child (or maggie-core to go back); checks the homepage before and after").action((slug, _o, c) => run(g(c), "wp_child_theme_activate", { slug }));
   child.command("restore <slug> <backup>").description("put a backup of the child's files back").action((slug, backup, _o, c) => run(g(c), "wp_child_theme_restore", { slug, backup }));
+  const guides = wp.command("guides").description("the child theme's guides for agents: DESIGN.md, AGENTS.md, MEMORY.md");
+  guides.command("get [slug]", { isDefault: true }).action((slug, _o, c) => run(g(c), "wp_site_guides_get", { slug }));
+  guides.command("set [slug]").option("--design-file <file>", "replace DESIGN.md").option("--agents-file <file>", "replace AGENTS.md").option("--memory-file <file>", "replace MEMORY.md").option("--refresh-design", "rewrite DESIGN.md from the site, keeping its Rules").option("--init", "write the missing guides from templates").action(
+    async (slug, o, c) => run(g(c), "wp_site_guides_set", {
+      slug,
+      design_md: o.designFile ? await readFile2(o.designFile, "utf8") : void 0,
+      agents_md: o.agentsFile ? await readFile2(o.agentsFile, "utf8") : void 0,
+      memory_md: o.memoryFile ? await readFile2(o.memoryFile, "utf8") : void 0,
+      refresh_design: o.refreshDesign,
+      init: o.init
+    })
+  );
+  wp.command("remember <kind> <text...>").description("add to MEMORY.md: kind prefer, avoid (a don't) or note").action(
+    (kind, text3, _o, c) => run(g(c), "wp_site_memory_add", { kind, text: text3.join(" ") })
+  );
   wp.command("child-theme <slug>").description(
     "export the site's look as a child theme folder on this computer (to keep in git); cmo wp child works on the site itself"
   ).requiredOption("--name <name>", 'theme name, e.g. "Moon Lake Spa"').option("--out <dir>", "where to write it (default ./<slug>)").option("--from-site", "take the brand, header and footer from the connected site").option("--color <slug=hex...>", "brand colours").option("--font <slug=family...>", "fonts (replaces Maggie Core's font list: ship their files too)").action(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cmo-so/cli",
-	"version": "0.12.10",
+	"version": "0.12.11",
 	"description": "CMO.so on the command line: your websites, ideas, blog posts, LinkedIn queue and results, plus a local MCP server for Claude Desktop, Cursor and other MCP clients.",
 	"type": "module",
 	"license": "MIT",