@caelo-cms/shared 0.10.72 → 0.11.0

package/src/ai-tools-add-module-modes.test.ts

@@ -104,3 +104,53 @@ describe("addModuleToolInput modes (issue #159)", () => {
     expect(r.success).toBe(false);
   });
 });
+
+describe("addModuleToolInput — list fields carry their own content (PR #1121 e2e)", () => {
+  const LIST = "caelo:list/22222222-2222-4222-8222-222222222222";
+  const footer = (fields: unknown[]) =>
+    addModuleToolInput.safeParse({
+      ...BASE,
+      target: "layout" as const,
+      targetRef: "site-default",
+      blockName: "footer",
+      displayName: "Footer",
+      html: '<nav>{{#footer_links}}<a href="{{link}}">{{label}}</a>{{/footer_links}}</nav>',
+      fields,
+    });
+
+  it("accepts a footer bound to a shared list without values or defaults", () => {
+    const r = footer([
+      {
+        name: "footer_links",
+        kind: "list",
+        label: "Links",
+        listType: "menu",
+        bind: "shared",
+        list: LIST,
+      },
+    ]);
+    expect(r.success).toBe(true);
+  });
+
+  it("accepts a list fed by a source", () => {
+    const r = footer([
+      {
+        name: "footer_links",
+        kind: "list",
+        label: "Crumbs",
+        listType: "links",
+        bind: "source",
+        source: { kind: "system", name: "breadcrumbs" },
+      },
+    ]);
+    expect(r.success).toBe(true);
+  });
+
+  it("still refuses a shared list field with no list and no value, naming the list route", () => {
+    const r = footer([
+      { name: "footer_links", kind: "list", label: "Links", listType: "menu", bind: "shared" },
+    ]);
+    expect(r.success).toBe(false);
+    expect(r.error?.issues[0]?.message).toContain("upsert_lists_many");
+  });
+});

package/src/ai-tools.test.ts

@@ -33,6 +33,16 @@ describe("editModuleToolInput", () => {
     });
     expect(r.success).toBe(false);
   });
+
+  // e2e-livedit run 40351690739 — `{moduleId}` alone reached the op.
+  it("refuses an edit that changes nothing, naming what to pass", () => {
+    for (const input of [{ moduleId: UUID }, { moduleId: UUID, bindThemeLiterals: false }]) {
+      const r = editModuleToolInput.safeParse(input);
+      expect(r.success).toBe(false);
+      if (!r.success) expect(r.error.issues[0]?.message).toContain("edit_module changes nothing");
+    }
+    expect(editModuleToolInput.safeParse({ moduleId: UUID, kind: "hero" }).success).toBe(true);
+  });
 });
 
 describe("siteMemoryProposeToolInput", () => {

package/src/ai-tools.ts

@@ -20,13 +20,16 @@ import {
   MODULE_CSS_MAX,
   MODULE_HTML_MAX,
   MODULE_JS_MAX,
+  type ModuleField,
   moduleFieldSchema,
+  pageTypeSlugSchema,
   setPlacementContentSchema,
   slugSchema,
 } from "./content.js";
+import { LIST_ITEM_ATTR_RE } from "./lists/item-attr.js";
 import { pluginPreviewSelectionSchema } from "./plugin-preview.js";
 import { redirectTargetPathSchema } from "./redirect-target.js";
-import { unwrapCdataEnvelope } from "./strip-cdata.js";
+import { decodeSourceTextTransport } from "./source-text-transport.js";
 
 /**
  * v0.6.2 — `position` argument shared across the three `add_module_to_*`
@@ -61,15 +64,16 @@ function stripSurroundingQuotes(v: unknown): unknown {
 }
 /**
  * An AI tool argument holding source text (html / css / js): the given
- * string schema, with a whole-value `<![CDATA[ … ]]>` transport envelope
- * decoded first (see `unwrapCdataEnvelope`). Every AI authoring surface for
- * module, template and layout source uses it, so one encoding habit of the
- * model is handled in one place instead of refused per tool.
+ * string schema, with whole-value transport encodings decoded first — a
+ * CDATA envelope, a JSON string literal, HTML-escaped markup (see
+ * `decodeSourceTextTransport`). Every AI authoring surface for module,
+ * template and layout source uses it, so one encoding habit of the model
+ * is handled in one place instead of refused per tool.
  *
  * @param schema - the string schema (length caps, min) the decoded value must satisfy.
  */
 export function sourceTextArg<T extends z.ZodType<string>>(schema: T) {
-  return z.preprocess(unwrapCdataEnvelope, schema);
+  return z.preprocess(decodeSourceTextTransport, schema);
 }
 
 export const positionInputSchema = z.preprocess(
@@ -114,7 +118,15 @@ export const editModuleToolInput = z
     /** issue #164 slice 2 — see addModuleToolInput.bindThemeLiterals. */
     bindThemeLiterals: z.boolean().optional(),
   })
-  .strict();
+  .strict()
+  // e2e-livedit run 40351690739: a call with only a (placeholder)
+  // moduleId reached the op and came back as a bare "module not found".
+  // An edit that changes nothing is refused before any lookup, with the
+  // fields that make it one.
+  .refine((v) => Object.keys(v).some((k) => k !== "moduleId" && k !== "bindThemeLiterals"), {
+    message:
+      "edit_module changes nothing: pass what to change (html, css, js, fields, displayName, description, kind or type). list_modules shows the modules; add_module creates a new one.",
+  });
 
 /**
  * v0.4.0 — `set_page_module_content` AI tool. Fills the content values for
@@ -274,17 +286,25 @@ export const addModuleToolInput = z
     // the exact two-step build_page was created to kill. Only enforced
     // when the caller authored explicit fields; the raw-HTML path goes
     // through moduleize, which enforces defaults itself.
+    // A `list` field bound to a shared list the module fixes (`list`), or
+    // fed by a source, already has its content: requiring a default there
+    // refused the very footer-bound-to-the-menu call the manage-menu skill
+    // prescribes (PR #1121 e2e-livedit run 40297574140).
+    const carriesContent = (f: ModuleField): boolean =>
+      ("default" in f && f.default !== undefined) ||
+      (f.kind === "list" && (f.bind === "source" || (f.bind === "shared" && f.list !== undefined)));
     if (
       input.fields !== undefined &&
       input.fields.length > 0 &&
       input.values === undefined &&
-      !input.fields.some((f) => "default" in f && f.default !== undefined)
+      !input.fields.some(carriesContent)
     ) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         message:
           "A minted module needs its initial content IN THIS CALL: pass `values` " +
           "({fieldName: value, …}) for this placement, or give the fields `default`s. " +
+          'A list field bound to a site list carries its content through `list` ({kind:"list", bind:"shared", list:"caelo:list/<id>"} — create the list first with upsert_lists_many). ' +
           "Without either, the module renders empty placeholders until a second call.",
       });
     }
@@ -355,7 +375,6 @@ export const AI_TOOLS = [
   "delete_pages_many",
   // one remove-module tool routed by target (page|layout).
   "remove_module_from",
-  "set_structured_set",
   "update_theme",
   "set_template_layout",
   "create_layout",
@@ -451,9 +470,14 @@ export const CHAT_MAX_ATTACHMENTS = 4;
  * `context` come from a right-click / text selection in the live-edit
  * preview (#916): what the operator selected and the text of the block
  * around it, so the AI knows exactly what was meant. `blockName` /
- * `position` / `field` / `index` (#917) name the placement field the text
+ * `position` / `field` (#917) — plus `item` / `key` for an entry of a
+ * local list field (epic #1107) — name the placement field the text
  * comes from when the preview marked it, so the AI can address it in
  * `set_page_module_content` without inspecting the page first.
+ * `listItem` is the `data-caelo-list-item` of the list entry the element
+ * sits in (epic #1107, `docs/lists.md` §13): the chip then names that
+ * entry — of a shared list, or of a module's own list — not just the
+ * module around it.
  */
 export const chatChipSchema = z
   .object({
@@ -465,7 +489,12 @@ export const chatChipSchema = z
     blockName: z.string().min(1).max(80).optional(),
     position: z.number().int().nonnegative().optional(),
     field: z.string().min(1).max(200).optional(),
-    index: z.number().int().nonnegative().optional(),
+    item: z.string().uuid().optional(),
+    key: z
+      .string()
+      .regex(/^[a-z][a-z0-9_]{0,63}$/)
+      .optional(),
+    listItem: z.string().max(200).regex(LIST_ITEM_ATTR_RE).optional(),
   })
   .strict();
 export type ChatChip = z.infer<typeof chatChipSchema>;
@@ -555,11 +584,8 @@ export const chatPublishInput = z
       .array(
         z
           .object({
-            // v0.9.0 — added "layout" + "structuredSet" to the enum so
-            // the Stage picker can include/exclude them. Pre-v0.9.0 the
-            // helper accepted "structuredSet" via the underlying SQL
-            // query but the input schema rejected it — minor gap closed
-            // alongside the branched-create work.
+            // v0.9.0 — "layout" joined the enum so the Stage picker can
+            // include/exclude it.
             kind: z.enum([
               "module",
               "template",
@@ -567,7 +593,10 @@ export const chatPublishInput = z
               "pageLayout",
               "pageModuleContent",
               "layout",
-              "structuredSet",
+              // Epic #1107 — shared lists, list types, page types.
+              "listType",
+              "list",
+              "pageType",
               // v0.11.0 (#45) — themes primitive joins the publish/Stage
               // surface so chat-branched theme edits replay into live
               // on chat.publish.
@@ -650,6 +679,8 @@ export const createTemplateToolInput = z
     html: sourceTextArg(z.string().min(1).max(2_000_000)),
     css: sourceTextArg(z.string().max(2_000_000)).default(""),
     layoutId: z.string().uuid().optional(),
+    /** Epic #1107 — the page type (slug) this template serves; omit for the site default. */
+    pageType: pageTypeSlugSchema.optional(),
     // Optional block-set metadata, symmetric with create_layout. Omit to
     // auto-derive blocks from <caelo-slot> tags; pass to set displayName /
     // position (each name must match a slot). Enforced op-side in
@@ -682,25 +713,9 @@ export const removeModuleFromToolInput = z
   .strict();
 export type RemoveModuleFromToolInput = z.infer<typeof removeModuleFromToolInput>;
 
-export const setStructuredSetToolInput = z
-  .object({
-    // structuredSetKind (the 6th kind that was previously unreachable
-    // from any AI tool — the kind-specific wrappers covered only
-    // nav-menu + theme).
-    kind: z.enum(["nav-menu", "taxonomy", "tags", "link-list"]),
-    slug: slugInputSchema,
-    displayName: z.string().min(1).max(200),
-    items: z.array(z.unknown()),
-  })
-  .strict();
-
-// v0.10.22 — `updateThemeToolInput` removed. The kind-specific `update_theme`
-// wrapper was replaced by the unified `set_structured_set` surface.
-// v0.11.0 (#45) — theme moved out of structured_sets entirely into its
-// own `themes` primitive (DTCG-shaped jsonb). Theme edits are now
-// `set_theme_tokens` (loose-name patch) / `propose_create_theme`
-// (gated mint) / `propose_activate_theme` (gated flip) — see
-// packages/admin-core/src/ai/tools/{update-theme-tokens,get-theme,…}.ts.
+// v0.11.0 (#45) — theme edits are `set_theme_tokens` (loose-name patch) /
+// `propose_create_theme` (gated mint) / `propose_activate_theme` (gated
+// flip) — see packages/admin-core/src/ai/tools/{update-theme-tokens,get-theme,…}.ts.
 
 export const setTemplateLayoutToolInput = z
   .object({
@@ -1037,7 +1052,6 @@ export type BulkOptimizeSeoToolInput = z.infer<typeof bulkOptimizeSeoToolInput>;
 export type EditModuleToolInput = z.infer<typeof editModuleToolInput>;
 export type SiteMemoryProposeToolInput = z.infer<typeof siteMemoryProposeToolInput>;
 export type CreateTemplateToolInput = z.infer<typeof createTemplateToolInput>;
-export type SetStructuredSetToolInput = z.infer<typeof setStructuredSetToolInput>;
 // v0.10.22 — `UpdateThemeToolInput` removed alongside `update_theme` tool.
 export type ChatCreateSessionInput = z.infer<typeof chatCreateSessionInput>;
 export type ChatSendMessageInput = z.infer<typeof chatSendMessageInput>;

package/src/build-page.test.ts

@@ -39,6 +39,14 @@ describe("buildPageInputSchema — page target modes", () => {
     expect(r.success).toBe(true);
   });
 
+  it("accepts parentPageId: null as top level, like pages.create (PR #1121 e2e)", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "pricing", title: "Pricing", parentPageId: null },
+      modules: [mintModule],
+    });
+    expect(r.success).toBe(true);
+  });
+
   it("accepts existing mode (pageId only)", () => {
     const r = buildPageInputSchema.safeParse({
       page: { pageId: UUID },
@@ -140,10 +148,10 @@ describe("buildPageInputSchema — module entry modes name the failing index", (
         {
           blockName: "content",
           displayName: "Nav",
-          html: "<nav>{{#nav_links}}<a href='{{href}}'>{{label}}</a>{{/nav_links}}</nav>",
+          html: "<nav>{{#nav_links}}<a href='{{link}}'>{{label}}</a>{{/nav_links}}</nav>",
           fields: [
-            { name: "nav_links", kind: "link-list", label: "Nav links" },
-            { name: "tags", kind: "text-list", label: "Tags", min: 0, max: 12 },
+            { name: "nav_links", kind: "list", listType: "links", label: "Nav links" },
+            { name: "tags", kind: "list", listType: "texts", label: "Tags", min: 0, max: 12 },
           ],
         },
       ],
@@ -190,6 +198,29 @@ describe("buildPageInputSchema — module entry modes name the failing index", (
   });
 });
 
+describe("buildPageInputSchema — ref handles", () => {
+  // e2e-livedit run 40336739359 (PR #1143): the AI named three cards
+  // `cardA` / `cardB` / `cardC` and the lowercase-only rule refused the
+  // whole call for a handle that never leaves it.
+  it("accepts mixed-case handles and refuses ones that do not start with a letter", () => {
+    const { blockName: _b, ...detached } = mintModule;
+    for (const ref of ["cardA", "card_b", "feat-1"]) {
+      const r = buildPageInputSchema.safeParse({
+        page: { pageId: UUID },
+        modules: [{ ...detached, ref }],
+      });
+      expect(r.success).toBe(true);
+    }
+    for (const ref of ["1card", "$card", "card a"]) {
+      const r = buildPageInputSchema.safeParse({
+        page: { pageId: UUID },
+        modules: [{ ...detached, ref }],
+      });
+      expect(r.success).toBe(false);
+    }
+  });
+});
+
 describe("buildPageContentSchema — the three sources", () => {
   it("inline requires values", () => {
     expect(buildPageContentSchema.safeParse({ source: "inline" }).success).toBe(false);

package/src/build-page.ts

@@ -28,6 +28,7 @@ import {
   MODULE_JS_MAX,
   moduleFieldSchema,
   moduleKindSchema,
+  pageCreateSchema,
   pageStatusSchema,
   slugSchema,
   syncModeSchema,
@@ -130,7 +131,10 @@ export const buildPageModuleSchema = z
      */
     ref: z
       .string()
-      .regex(/^[a-z][a-z0-9_-]{0,31}$/, "ref must be a short lowercase handle")
+      .regex(
+        /^[A-Za-z][A-Za-z0-9_-]{0,31}$/,
+        "ref must be a short handle: a letter, then letters, digits, _ or -",
+      )
       .optional(),
     /**
      * Place mode: an existing module from `list_modules` (UUID), or a
@@ -224,7 +228,16 @@ export const buildPageTargetSchema = z
      * "<parent's path>/<slug>". Create mode only (an existing page moves
      * with `pages.move_many`).
      */
-    parentPageId: z.string().uuid().optional(),
+    // null = top level, same as pages.create (sibling tools must agree — #106 class).
+    parentPageId: z.string().uuid().nullable().optional(),
+    /**
+     * Epic #1107 — what the new page IS (page type slug), its properties
+     * and terms; same semantics as `pages.create` (create mode only — an
+     * existing page changes type with `pages.update`).
+     */
+    pageType: pageCreateSchema.shape.pageType,
+    properties: pageCreateSchema.shape.properties,
+    terms: pageCreateSchema.shape.terms,
     /**
      * Migration linkage (issue #278 flow): the `import_pages` row this
      * page rebuilds. The op stamps `import_pages.accepted_page_id` with
@@ -252,7 +265,17 @@ export const buildPageTargetSchema = z
   .strict()
   .superRefine((page, ctx) => {
     const createKeys = (
-      ["slug", "title", "name", "templateId", "status", "parentPageId"] as const
+      [
+        "slug",
+        "title",
+        "name",
+        "templateId",
+        "status",
+        "parentPageId",
+        "pageType",
+        "properties",
+        "terms",
+      ] as const
     ).filter((k) => page[k] !== undefined);
     if (page.pageId !== undefined) {
       if (createKeys.length > 0) {

package/src/content.test.ts

@@ -10,6 +10,7 @@ import {
   pageUpdateSchema,
   slugSchema,
   templateBlocksSetSchema,
+  templateCreateSchema,
 } from "./content.js";
 
 describe("slugSchema", () => {
@@ -120,8 +121,9 @@ describe("moduleFields numbered-scalar fanout guard (§1A)", () => {
       expect(msg).toContain("numbered-scalar fanout");
       expect(msg).toContain('"label", "label2", "label3"');
       // AI-actionable: the error names every list-kind fix.
-      expect(msg).toContain("text-list");
-      expect(msg).toContain("link-list");
+      expect(msg).toContain('kind "list"');
+      expect(msg).toContain('listType "texts"');
+      expect(msg).toContain('"links"');
       expect(msg).toContain("module-list");
       expect(msg).toContain("§1A");
     }
@@ -153,11 +155,83 @@ describe("moduleFields numbered-scalar fanout guard (§1A)", () => {
   });
 
   it("scopes to scalar kinds — numbered list fields are a modelling question, not fanout", () => {
-    const linkList = (name: string) => ({ name, kind: "link-list", label: name });
+    const linkList = (name: string) => ({ name, kind: "list", listType: "links", label: name });
     expect(mod([linkList("links1"), linkList("links2"), linkList("links3")]).success).toBe(true);
   });
 });
 
+// Epic #1107 — the `list` field kind (docs/lists.md §7): the static
+// schema checks the binding's shape; fitting the type is the op's job.
+describe("moduleFields list kind", () => {
+  const mod = (fields: unknown) =>
+    moduleCreateSchema.safeParse({ slug: "m", displayName: "M", html: "<div></div>", fields });
+  const LIST = "caelo:list/00000000-0000-4000-8000-000000000101";
+  const messages = (r: ReturnType<typeof mod>) =>
+    r.success ? [] : r.error.issues.map((i) => i.message);
+
+  it("accepts every binding", () => {
+    const ok = mod([
+      {
+        name: "bullets",
+        label: "B",
+        kind: "list",
+        listType: "texts",
+        default: [{ node: "text", values: { text: "x" } }],
+      },
+      { name: "menu", label: "M", kind: "list", listType: "menu", bind: "shared", list: LIST },
+      {
+        name: "footer",
+        label: "F",
+        kind: "list",
+        listType: "links",
+        bind: "shared",
+        default: LIST,
+      },
+      {
+        name: "latest",
+        label: "L",
+        kind: "list",
+        listType: "links",
+        bind: "source",
+        source: {
+          kind: "query",
+          editable: ["limit"],
+          defaults: { page_type: "news", order: "published_desc", limit: 3 },
+        },
+      },
+      {
+        name: "crumbs",
+        label: "C",
+        kind: "list",
+        listType: "links",
+        bind: "source",
+        source: { kind: "system", name: "breadcrumbs" },
+      },
+    ]);
+    expect(ok.success).toBe(true);
+  });
+
+  it("refuses bindings whose parts do not fit together, naming the fix", () => {
+    const r = mod([
+      { name: "a", label: "A", kind: "list", listType: "menu", bind: "source" },
+      { name: "b", label: "B", kind: "list", listType: "menu", list: LIST },
+      { name: "c", label: "C", kind: "list", listType: "menu", bind: "shared", default: [] },
+      { name: "d", label: "D", kind: "list", listType: "texts", default: LIST },
+    ]);
+    expect(messages(r)).toEqual([
+      'list field "a": bind "source" needs a source (query, system or plugin).',
+      'list field "b": list is only allowed with bind "shared" — a local list stores its entries in the placement.',
+      'list field "c": a shared default is caelo:list/<id> — create the list with upsert_lists_many first.',
+      'list field "d": a local default is an array of entries, not a list reference.',
+    ]);
+  });
+
+  it("refuses the removed text-list / link-list kinds", () => {
+    expect(mod([{ name: "t", label: "T", kind: "text-list" }]).success).toBe(false);
+    expect(mod([{ name: "l", label: "L", kind: "link-list" }]).success).toBe(false);
+  });
+});
+
 describe("pageCreateSchema (no raw HTML invariant)", () => {
   it("accepts a structured page payload", () => {
     const r = pageCreateSchema.safeParse({
@@ -250,3 +324,37 @@ describe("templateBlocksSetSchema", () => {
     expect(r.success).toBe(true);
   });
 });
+
+describe("corrupted code payloads are refused at the boundary (PR #1121 e2e)", () => {
+  const base = { slug: "footer", displayName: "Footer", html: "<footer>x</footer>" };
+  it("refuses JSON-encoded html and css with the fix in the message", () => {
+    const html = moduleCreateSchema.safeParse({
+      ...base,
+      html: JSON.stringify('<footer class="x">{{#links}}{{label}}{{/links}}</footer>'),
+    });
+    expect(html.success).toBe(false);
+    expect(html.error?.issues[0]?.message).toContain("JSON-encoded");
+    const css = moduleCreateSchema.safeParse({
+      ...base,
+      css: JSON.stringify(".x { color: red; }"),
+    });
+    expect(css.success).toBe(false);
+  });
+  it("refuses HTML-escaped template markup", () => {
+    const r = templateCreateSchema.safeParse({
+      slug: "page",
+      displayName: "Page",
+      html: '&lt;div&gt;&lt;caelo-slot name="content"&gt;&lt;/caelo-slot&gt;&lt;/div&gt;',
+    });
+    expect(r.success).toBe(false);
+    expect(r.error?.issues[0]?.message).toContain("HTML-escaped");
+  });
+  it("keeps legitimate markup: entities inside real tags, a quote-led text node", () => {
+    expect(
+      moduleCreateSchema.safeParse({ ...base, html: "<pre>&lt;div&gt; is a tag</pre>" }).success,
+    ).toBe(true);
+    expect(moduleCreateSchema.safeParse({ ...base, html: '"Quoted" <em>text</em>' }).success).toBe(
+      true,
+    );
+  });
+});