@agent-native/core 0.79.26 → 0.80.0

package/corpus/templates/content/actions/_document-flush.ts

@@ -0,0 +1,62 @@
+import {
+  appStateDelete,
+  appStateGet,
+  appStatePut,
+} from "@agent-native/core/application-state";
+import { hasCollabState } from "@agent-native/core/collab";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+
+const FLUSH_POLL_INTERVAL_MS = 200;
+const FLUSH_TIMEOUT_MS = 4000;
+
+export async function flushOpenDocumentEditorToSql(args: {
+  documentId: string;
+  ownerEmail?: string | null;
+}) {
+  // If a live Yjs collab session is open, the in-memory editor doc is fresher
+  // than the SQL column. Ask the open editor to serialize + save, then wait
+  // for it to acknowledge by clearing the flush-request key.
+  if (!(await hasCollabState(args.documentId))) return;
+
+  const flushKey = `flush-request-${args.documentId}`;
+  // The editor polls `flush-request-<id>` via the framework app-state route,
+  // which scopes reads to the logged-in browser user (the document owner).
+  // Writing under the caller's (external agent's) session alone can miss the
+  // human editor tab, so write under both plausible sessions and de-dupe.
+  const callerEmail = getRequestUserEmail() || undefined;
+  const targetSessions = Array.from(
+    new Set(
+      [args.ownerEmail ?? undefined, callerEmail].filter(
+        (s): s is string => typeof s === "string" && s.length > 0,
+      ),
+    ),
+  );
+  if (targetSessions.length === 0) return;
+
+  const flushValue = { id: args.documentId, ts: Date.now() };
+  await Promise.all(
+    targetSessions.map((session) =>
+      appStatePut(session, flushKey, flushValue, {
+        requestSource: "agent",
+      }).catch(() => {}),
+    ),
+  );
+
+  const deadline = Date.now() + FLUSH_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, FLUSH_POLL_INTERVAL_MS));
+    const pending = await Promise.all(
+      targetSessions.map((session) => appStateGet(session, flushKey)),
+    );
+    if (pending.every((value) => !value)) break;
+  }
+
+  // Best-effort cleanup if the editor never picked it up (no tab open).
+  await Promise.all(
+    targetSessions.map((session) =>
+      appStateDelete(session, flushKey, { requestSource: "agent" }).catch(
+        () => {},
+      ),
+    ),
+  );
+}

package/corpus/templates/content/actions/_local-file-documents.ts

@@ -20,6 +20,7 @@ import type {
 import { parseContentSourceFile } from "../shared/content-source.js";
 
 const CONTENT_APP_ID = "content";
+const CONTENT_PROFILE_DOCS_NO_BOOKKEEPING = "docs/no-bookkeeping";
 const LOCAL_FILE_ID_PREFIX = "local-file:";
 const LOCAL_FOLDER_ID_PREFIX = "local-folder:";
 const FRONTMATTER_RE =
@@ -202,6 +203,7 @@ function documentFromLocalFile(
       absolutePath,
       rootName: file.rootName,
       rootPath: file.rootPath,
+      profile: file.profile,
       hash: file.hash,
       contentType: file.contentType,
       sizeBytes: file.sizeBytes,
@@ -267,10 +269,23 @@ function frontmatterLine(key: string, value: unknown) {
   return `${key}: ${JSON.stringify(String(value))}`;
 }
 
+function shouldAddMissingFrontmatterKey(
+  key: string,
+  addMissingKeys: UpsertFrontmatterOptions["addMissingKeys"],
+) {
+  if (typeof addMissingKeys === "function") return addMissingKeys(key);
+  return addMissingKeys ?? true;
+}
+
+interface UpsertFrontmatterOptions {
+  addMissingKeys?: boolean | ((key: string) => boolean);
+}
+
 function upsertFrontmatter(
   original: string,
   fields: Record<string, unknown>,
   body: string,
+  options: UpsertFrontmatterOptions = {},
 ) {
   const { frontmatter } = splitFrontmatter(original);
   const lines = frontmatter ? frontmatter.split(/\r?\n/) : [];
@@ -286,9 +301,14 @@ function upsertFrontmatter(
 
   for (const [key, value] of Object.entries(fields)) {
     if (usedKeys.has(key) || value === undefined) continue;
+    if (!shouldAddMissingFrontmatterKey(key, options.addMissingKeys)) continue;
     nextLines.push(frontmatterLine(key, value));
   }
 
+  if (!frontmatter && nextLines.filter(Boolean).length === 0) {
+    return body;
+  }
+
   return `---\n${nextLines.filter(Boolean).join("\n")}\n---\n\n${body}`;
 }
 
@@ -304,6 +324,77 @@ function stripDuplicateTitleHeading(content: string, title: string) {
   return content;
 }
 
+function nextContentForLocalUpdate(
+  file: LocalArtifactFile,
+  args: DocumentUpdateRequest,
+  current: Document,
+  nextTitle: string,
+) {
+  if (args.content === undefined) return current.content;
+  if (usesDocsNoBookkeepingProfile(file.profile)) return args.content;
+  return stripDuplicateTitleHeading(args.content, nextTitle);
+}
+
+function contentForLocalCreate(
+  profile: string | undefined,
+  args: DocumentCreateRequest,
+  title: string,
+) {
+  const content = args.content ?? "";
+  if (usesDocsNoBookkeepingProfile(profile)) return content;
+  return stripDuplicateTitleHeading(content, title);
+}
+
+function usesDocsNoBookkeepingProfile(profile?: string) {
+  return profile === CONTENT_PROFILE_DOCS_NO_BOOKKEEPING;
+}
+
+function updateFrontmatterFields(
+  file: LocalArtifactFile,
+  current: Document,
+  args: DocumentUpdateRequest,
+  nextTitle: string,
+  titleChanged: boolean,
+  iconChanged: boolean,
+  favoriteChanged: boolean,
+) {
+  if (usesDocsNoBookkeepingProfile(file.profile)) {
+    return {
+      ...(titleChanged ? { title: nextTitle || "Untitled" } : {}),
+      ...(iconChanged ? { icon: args.icon ?? null } : {}),
+      ...(favoriteChanged ? { isFavorite: args.isFavorite ?? false } : {}),
+    };
+  }
+
+  return {
+    title: nextTitle || "Untitled",
+    icon: args.icon !== undefined ? args.icon : current.icon,
+    isFavorite:
+      args.isFavorite !== undefined ? args.isFavorite : current.isFavorite,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function createFrontmatterFields(
+  profile: string | undefined,
+  args: DocumentCreateRequest,
+  title: string,
+) {
+  if (usesDocsNoBookkeepingProfile(profile)) {
+    return {
+      title,
+      ...(args.icon !== undefined ? { icon: args.icon || null } : {}),
+    };
+  }
+
+  return {
+    title,
+    icon: args.icon || null,
+    isFavorite: false,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
 export async function updateLocalFileDocument(
   id: string,
   args: DocumentUpdateRequest,
@@ -318,10 +409,7 @@ export async function updateLocalFileDocument(
 
   const current = documentFromLocalFile(file, file.content, 0);
   const nextTitle = args.title ?? current.title;
-  const nextContent =
-    args.content === undefined
-      ? current.content
-      : stripDuplicateTitleHeading(args.content, nextTitle);
+  const nextContent = nextContentForLocalUpdate(file, args, current, nextTitle);
   const titleChanged = args.title !== undefined && args.title !== current.title;
   const contentChanged =
     args.content !== undefined && nextContent !== current.content;
@@ -335,13 +423,15 @@ export async function updateLocalFileDocument(
 
   const nextSource = upsertFrontmatter(
     file.content,
-    {
-      title: nextTitle || "Untitled",
-      icon: args.icon !== undefined ? args.icon : current.icon,
-      isFavorite:
-        args.isFavorite !== undefined ? args.isFavorite : current.isFavorite,
-      updatedAt: new Date().toISOString(),
-    },
+    updateFrontmatterFields(
+      file,
+      current,
+      args,
+      nextTitle,
+      titleChanged,
+      iconChanged,
+      favoriteChanged,
+    ),
     nextContent,
   );
 
@@ -364,6 +454,16 @@ async function chooseCreateDirectory(parentId?: string | null) {
   return (await ensureLocalArtifactRoot(localOptions())).path;
 }
 
+async function profileForDirectory(directory: string) {
+  const app = await getLocalArtifactApp(localOptions());
+  const root = app.roots.find(
+    (candidate) =>
+      directory === candidate.path ||
+      directory.startsWith(`${candidate.path}/`),
+  );
+  return root?.profile ?? app.profile;
+}
+
 async function uniqueFilePath(directory: string, title: string) {
   const existing = new Set(
     (await listLocalArtifactFiles(localOptions())).map((file) => file.path),
@@ -387,15 +487,11 @@ export async function createLocalFileDocument(
 ): Promise<Document> {
   const title = args.title || "Untitled";
   const directory = await chooseCreateDirectory(args.parentId ?? null);
-  const content = stripDuplicateTitleHeading(args.content ?? "", title);
+  const profile = await profileForDirectory(directory);
+  const content = contentForLocalCreate(profile, args, title);
   const source = upsertFrontmatter(
     "",
-    {
-      title,
-      icon: args.icon || null,
-      isFavorite: false,
-      updatedAt: new Date().toISOString(),
-    },
+    createFrontmatterFields(profile, args, title),
     content,
   );
 
@@ -446,6 +542,7 @@ export async function localContentViewScreenSummary() {
       name: root.name,
       path: root.path,
       kind: root.kind,
+      profile: root.profile,
       extensions: root.extensions,
     })),
     documents: documents.map((document) => ({

package/corpus/templates/content/actions/check-builder-doc.ts

@@ -0,0 +1,38 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { checkBuilderDocsSource } from "./_builder-docs-client.js";
+
+export default defineAction({
+  description:
+    "Validate a Builder .builder.mdx document before push: raw sidecars, local round-trip, and remote conflict gate.",
+  schema: z.object({
+    documentId: z.string().optional().describe("Content document ID."),
+    id: z.string().optional().describe("Alias for --documentId."),
+    path: z
+      .string()
+      .optional()
+      .describe("Specific .builder.mdx path inside the files map."),
+    files: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe(
+        "Map of relative file path to file contents, including the .builder.mdx file and content/builder/.raw sidecars.",
+      ),
+  }),
+  publicAgent: {
+    expose: true,
+    readOnly: true,
+    requiresAuth: true,
+    title: "Check Builder Doc",
+    description:
+      "Validate Builder MDX files and block pushes when the remote entry changed.",
+  },
+  run: async ({ documentId, id, path, files }) => {
+    return await checkBuilderDocsSource({
+      documentId: documentId || id,
+      path,
+      files,
+    });
+  },
+});

package/corpus/templates/content/actions/delete-document.ts

@@ -50,6 +50,14 @@ async function deleteRecursive(
         eq(schema.documentVersions.ownerEmail, ownerEmail),
       ),
     );
+  await db
+    .delete(schema.builderDocSidecars)
+    .where(
+      and(
+        eq(schema.builderDocSidecars.documentId, id),
+        eq(schema.builderDocSidecars.ownerEmail, ownerEmail),
+      ),
+    );
   await db
     .delete(schema.documentShares)
     .where(eq(schema.documentShares.resourceId, id));

package/corpus/templates/content/actions/import-content-source.ts

@@ -10,6 +10,7 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import {
+  isBuilderMdxSourcePath,
   isContentSourcePath,
   parseContentSourceFile,
   type ParsedContentSourceFile,
@@ -165,6 +166,17 @@ export default defineAction({
       "Import local Markdown/MDX source files into editable Content documents.",
   },
   run: async ({ files, dryRun }) => {
+    const builderPaths = Object.keys(files).filter((filePath) =>
+      isBuilderMdxSourcePath(filePath),
+    );
+    if (builderPaths.length > 0) {
+      throw new Error(
+        `Builder .builder.mdx files must use the Builder doc actions so raw sidecars and hashes are preserved: ${builderPaths.join(
+          ", ",
+        )}.`,
+      );
+    }
+
     const entries = normalizedFileEntries(files);
     if (entries.length === 0) {
       throw new Error("No .md or .mdx files were provided.");

package/corpus/templates/content/actions/list-builder-docs.ts

@@ -0,0 +1,29 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { BUILDER_DOCS_MODELS } from "../shared/builder-mdx.js";
+import { listBuilderDocsEntries } from "./_builder-docs-client.js";
+
+export default defineAction({
+  description:
+    "List published Builder.io docs/blog entries that can be pulled into Content as .builder.mdx.",
+  schema: z.object({
+    model: z
+      .enum(BUILDER_DOCS_MODELS as unknown as [string, ...string[]])
+      .optional()
+      .default("docs-content")
+      .describe("Builder model to list, usually docs-content or blog-article."),
+    limit: z.number().int().min(1).max(1000).optional().default(100),
+  }),
+  publicAgent: {
+    expose: true,
+    readOnly: true,
+    requiresAuth: true,
+    title: "List Builder Docs",
+    description:
+      "List published Builder docs/blog entries available for MDX pull.",
+  },
+  run: async ({ model, limit }) => {
+    return await listBuilderDocsEntries({ model, limit });
+  },
+});

package/corpus/templates/content/actions/pull-builder-doc.ts

@@ -0,0 +1,42 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { BUILDER_DOCS_MODELS } from "../shared/builder-mdx.js";
+import { pullBuilderDocIntoContent } from "./_builder-docs-client.js";
+
+export default defineAction({
+  description:
+    "Pull a Builder.io docs/blog entry into Content as an editable document and return its .builder.mdx plus raw sidecar files.",
+  schema: z.object({
+    model: z
+      .enum(BUILDER_DOCS_MODELS as unknown as [string, ...string[]])
+      .optional()
+      .default("docs-content")
+      .describe("Builder model, usually docs-content or blog-article."),
+    entryId: z.string().optional().describe("Builder entry/content ID."),
+    id: z.string().optional().describe("Alias for --entryId."),
+    dryRun: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe("Preview the pull without writing the Content document."),
+  }),
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+    title: "Pull Builder Doc",
+    description:
+      "Pull a Builder docs/blog entry into Content and return local MDX files.",
+  },
+  run: async ({ model, entryId, id, dryRun }) => {
+    const targetEntryId = entryId || id;
+    if (!targetEntryId) throw new Error("entryId is required.");
+    return await pullBuilderDocIntoContent({
+      model,
+      entryId: targetEntryId,
+      dryRun,
+    });
+  },
+});

package/corpus/templates/content/actions/pull-document.ts

@@ -1,15 +1,10 @@
 import { defineAction } from "@agent-native/core";
-import {
-  appStateGet,
-  appStatePut,
-  appStateDelete,
-} from "@agent-native/core/application-state";
-import { hasCollabState } from "@agent-native/core/collab";
-import { buildDeepLink, getRequestUserEmail } from "@agent-native/core/server";
+import { buildDeepLink } from "@agent-native/core/server";
 import { resolveAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
 import "../server/db/index.js";
+import { flushOpenDocumentEditorToSql } from "./_document-flush.js";
 import {
   getLocalFileDocument,
   isContentLocalFileMode,
@@ -42,14 +37,11 @@ import {
  *      is the best available snapshot.
  *
  * When there is no live collab session the DB column is authoritative and we
- * skip the handshake entirely. The handshake itself is bounded by
- * FLUSH_TIMEOUT_MS so a stale `hasCollabState` (presence lingering with no tab
- * actually open) can never hang the request longer than a few seconds.
+ * skip the handshake entirely. The helper bounds the wait so stale collab
+ * presence with no tab actually open can never hang the request longer than a
+ * few seconds.
  */
 
-const FLUSH_POLL_INTERVAL_MS = 200;
-const FLUSH_TIMEOUT_MS = 4000;
-
 function formatDocumentContent(markdown: string, format: "markdown" | "text") {
   return format === "text"
     ? markdown
@@ -99,52 +91,10 @@ export default defineAction({
     // If a live Yjs collab session is open, the in-memory editor doc is fresher
     // than the SQL column. Ask the open editor to serialize + save, then wait
     // for it to acknowledge by clearing the flush-request key.
-    if (await hasCollabState(id)) {
-      const flushKey = `flush-request-${id}`;
-      // The editor polls `flush-request-<id>` via the framework app-state
-      // route, which scopes reads to the logged-in browser user (the document
-      // owner). Writing under the caller's (external agent's) session — what
-      // the old `writeAppState` helper did — meant the editor never saw the
-      // key. Write under the owner's session so the open editor's poll picks
-      // it up; also write under the caller's own session for back-compat (e.g.
-      // an in-app agent that is itself the owner), de-duped.
-      const ownerEmail =
-        (access.resource.ownerEmail as string | undefined) || undefined;
-      const callerEmail = getRequestUserEmail() || undefined;
-      const targetSessions = Array.from(
-        new Set(
-          [ownerEmail, callerEmail].filter(
-            (s): s is string => typeof s === "string" && s.length > 0,
-          ),
-        ),
-      );
-      const flushValue = { id, ts: Date.now() };
-      await Promise.all(
-        targetSessions.map((s) =>
-          appStatePut(s, flushKey, flushValue, {
-            requestSource: "agent",
-          }).catch(() => {}),
-        ),
-      );
-      const deadline = Date.now() + FLUSH_TIMEOUT_MS;
-      while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, FLUSH_POLL_INTERVAL_MS));
-        // The editor deletes the key from whichever session it polls. Treat
-        // the flush as acknowledged once it is gone from all target sessions.
-        const pending = await Promise.all(
-          targetSessions.map((s) => appStateGet(s, flushKey)),
-        );
-        if (pending.every((p) => !p)) break;
-      }
-      // Best-effort cleanup if the editor never picked it up (no tab open).
-      await Promise.all(
-        targetSessions.map((s) =>
-          appStateDelete(s, flushKey, { requestSource: "agent" }).catch(
-            () => {},
-          ),
-        ),
-      );
-    }
+    await flushOpenDocumentEditorToSql({
+      documentId: id,
+      ownerEmail: (access.resource.ownerEmail as string | undefined) || null,
+    });
 
     // Re-resolve so we read the now-fresh row (and re-check access).
     const fresh = await resolveAccess("document", id);

package/corpus/templates/content/actions/push-builder-doc.ts

@@ -0,0 +1,45 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { pushBuilderDocsSource } from "./_builder-docs-client.js";
+
+export default defineAction({
+  description:
+    "Push a Builder .builder.mdx document body to Builder via a guarded autosave PATCH. Live writes are currently restricted to the safe Builder test model.",
+  schema: z.object({
+    documentId: z.string().optional().describe("Content document ID."),
+    id: z.string().optional().describe("Alias for --documentId."),
+    path: z
+      .string()
+      .optional()
+      .describe("Specific .builder.mdx path inside the files map."),
+    files: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe(
+        "Map of relative file path to file contents, including the .builder.mdx file and content/builder/.raw sidecars.",
+      ),
+    dryRun: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Preview the PATCH request without calling Builder."),
+  }),
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+    title: "Push Builder Doc",
+    description:
+      "Validate and autosave a Builder MDX body back to the safe Builder model.",
+  },
+  run: async ({ documentId, id, path, files, dryRun }) => {
+    return await pushBuilderDocsSource({
+      documentId: documentId || id,
+      path,
+      files,
+      dryRun,
+    });
+  },
+});