@agent-native/core-corpus 0.212.1 → 0.213.1

package/corpus/templates/content/actions/link-github-folder.ts

@@ -7,6 +7,7 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import { documentChangeResource } from "../server/lib/document-change-resource.js";
+import type { GitHubLinkBlockedReason } from "../shared/github-source.js";
 import {
   getContentDatabaseSourceSnapshot,
   resolveDatabaseForSourceMutation,
@@ -18,6 +19,8 @@ import {
   previewGitHubFolder,
   resolveGitHubFolder,
   syncGitHubSource,
+  unexpectedSyncFailure,
+  type GitHubSyncResult,
 } from "./_github-source.js";
 import { serializeDatabase } from "./_property-utils.js";
 
@@ -62,15 +65,10 @@ const linkGitHubFolderSchema = z
     "Provide exactly one databaseId or documentId",
   );
 
-type LinkBlocked =
-  | "collection-has-rows"
-  | "already-linked"
-  | "system-collection";
-
 async function linkBlockedReason(
   database: { id: string; systemRole: string | null },
   db: ReturnType<typeof getDb> = getDb(),
-): Promise<LinkBlocked | null> {
+): Promise<GitHubLinkBlockedReason | null> {
   if (database.systemRole) return "system-collection";
   const [source] = await db
     .select({ id: schema.contentDatabaseSources.id })
@@ -95,14 +93,14 @@ async function linkBlockedReason(
   return row ? "collection-has-rows" : null;
 }
 
-const BLOCKED_MESSAGES: Record<LinkBlocked, string> = {
+const BLOCKED_MESSAGES: Record<GitHubLinkBlockedReason, string> = {
   "collection-has-rows":
     "This collection already has rows. Link a GitHub folder from a new, empty collection.",
   "already-linked": "This collection is already linked to a source.",
   "system-collection": "This collection can't be linked to a GitHub folder.",
 };
 
-function blockedError(blocked: LinkBlocked) {
+function blockedError(blocked: GitHubLinkBlockedReason) {
   return new ActionContractError(BLOCKED_MESSAGES[blocked], {
     errorCode:
       blocked === "collection-has-rows"
@@ -114,6 +112,96 @@ function blockedError(blocked: LinkBlocked) {
   });
 }
 
+/**
+ * Links a collection to a folder already read and previewed, then brings in
+ * the first files. The link is saved before the sync, so a sync that fails is
+ * reported on the link rather than thrown.
+ */
+export async function linkPreviewedGitHubFolder({
+  database,
+  resolved,
+  preview,
+  connectionId,
+  userEmail,
+}: {
+  database: Parameters<typeof createGitHubSourceLink>[0]["database"];
+  resolved: Awaited<ReturnType<typeof resolveGitHubFolder>>;
+  preview: Awaited<ReturnType<typeof previewGitHubFolder>>;
+  connectionId: string | null;
+  userEmail: string;
+}) {
+  const sourceId = await createGitHubSourceLink({
+    database,
+    resolved,
+    preview,
+    connectionId,
+    userEmail,
+    // Reading GitHub takes seconds, so someone may have added a row since
+    // the check above; this runs again under the collection's lock.
+    assertLinkable: async (tx) => {
+      const blockedNow = await linkBlockedReason(database, tx);
+      if (blockedNow) throw blockedError(blockedNow);
+    },
+  });
+  return bringInGitHubLink({ database, preview, sourceId });
+}
+
+/**
+ * Brings in a saved link's first files, or the rest of them on a retry, and
+ * says how far it got.
+ */
+export async function bringInGitHubLink({
+  database,
+  preview,
+  sourceId,
+}: {
+  database: Parameters<typeof createGitHubSourceLink>[0]["database"];
+  preview: Awaited<ReturnType<typeof previewGitHubFolder>>;
+  sourceId: string;
+}) {
+  // The link is saved by now, so anything that fails from here is reported
+  // on it rather than thrown, which would leave the caller thinking it failed.
+  // A contract error is the exception: the link or its collection went away
+  // during the sync, so there's nothing left to report on.
+  let sync: GitHubSyncResult;
+  try {
+    sync = await syncGitHubSource({
+      sourceId,
+      budgetMs: FIRST_SYNC_BUDGET_MS,
+    });
+  } catch (error) {
+    if (error instanceof ActionContractError) throw error;
+    console.warn(
+      "[github-source] first sync failed:",
+      error instanceof Error ? error.message : String(error),
+    );
+    sync = unexpectedSyncFailure(new Date().toISOString());
+  }
+  await writeAppState("refresh-signal", { ts: Date.now() }).catch(
+    (error: unknown) => {
+      // The change event below still reaches open pages.
+      console.warn(
+        "[github-source] refresh signal failed:",
+        error instanceof Error ? error.message : String(error),
+      );
+    },
+  );
+  // coercion-ok: the status line reads the link on its own; this is a courtesy copy.
+  const source = await getContentDatabaseSourceSnapshot(database).catch(
+    () => null,
+  );
+  return {
+    sync,
+    source,
+    summary:
+      sync.state === "partial"
+        ? `Linked ${preview.label}. ${sync.created} of ${preview.markdownFiles} rows are in; the rest follow within about a minute.`
+        : sync.state === "error"
+          ? `Linked ${preview.label}, but the first sync failed: ${sync.problem?.message ?? "GitHub sync failed."}`
+          : `Linked ${preview.label}: ${sync.created} rows from commit ${sync.commitSha?.slice(0, 7) ?? "unknown"}.${sync.problem ? ` ${sync.problem.message}` : ""}`,
+  };
+}
+
 export default defineAction({
   description:
     "Link an empty content collection to a GitHub folder, view only: each Markdown file becomes a row, frontmatter becomes read-only columns, and pushes to the branch arrive on their own. Run with dryRun first to see the file count, skipped files with reasons, and the columns and types the frontmatter becomes.",
@@ -163,44 +251,24 @@ export default defineAction({
         preview,
         canLink: blocked === null,
         blocked: blocked ? BLOCKED_MESSAGES[blocked] : null,
+        blockedReason: blocked,
         summary: blocked
           ? BLOCKED_MESSAGES[blocked]
           : `${githubPreviewSummary(preview)} Run again without dryRun to link it.`,
       };
     }
 
-    const sourceId = await createGitHubSourceLink({
-      database,
-      resolved,
-      preview,
-      connectionId,
-      userEmail,
-      // Reading GitHub takes seconds, so someone may have added a row since
-      // the check above; this runs again under the collection's lock.
-      assertLinkable: async (tx) => {
-        const blockedNow = await linkBlockedReason(database, tx);
-        if (blockedNow) throw blockedError(blockedNow);
-      },
-    });
-    const sync = await syncGitHubSource({
-      sourceId,
-      budgetMs: FIRST_SYNC_BUDGET_MS,
-      throwConnectionErrors: true,
-    });
-    await writeAppState("refresh-signal", { ts: Date.now() });
-    const source = await getContentDatabaseSourceSnapshot(database);
     return {
       dryRun: false,
       database: serializeDatabase(database),
       preview,
-      sync,
-      source,
-      summary:
-        sync.state === "partial"
-          ? `Linked ${preview.label}. ${sync.created} of ${preview.markdownFiles} rows are in; sync again to load the rest.`
-          : sync.state === "error"
-            ? `Linked ${preview.label}, but the first sync failed: ${sync.problem?.message ?? "GitHub sync failed."}`
-            : `Linked ${preview.label}: ${sync.created} rows from commit ${sync.commitSha?.slice(0, 7) ?? "unknown"}.${sync.problem ? ` ${sync.problem.message}` : ""}`,
+      ...(await linkPreviewedGitHubFolder({
+        database,
+        resolved,
+        preview,
+        connectionId,
+        userEmail,
+      })),
     };
   },
   // Everyone reading the collection gets its new rows, not just the caller.

package/corpus/templates/content/actions/refresh-content-database-source.ts

@@ -1,4 +1,5 @@
 import { defineAction } from "@agent-native/core/action";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { assertAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
@@ -18,7 +19,11 @@ import {
   storeSecondarySourceRows,
   updateReadOnlySourceMetadata,
 } from "./_database-source-utils.js";
-import { githubSyncChangedRows } from "./_github-source-freshness.js";
+import {
+  announceGitHubSyncChange,
+  githubSyncChangedRows,
+  readGitHubStatusShown,
+} from "./_github-source-freshness.js";
 import { githubSyncSummary, syncGitHubSource } from "./_github-source.js";
 import { serializeDatabase } from "./_property-utils.js";
 
@@ -80,13 +85,41 @@ export default defineAction({
     let githubSummary: string | null = null;
     let githubChanged = false;
     if (source.sourceType === "github") {
+      const shownBefore = await readGitHubStatusShown(source.id);
       const result = await syncGitHubSource({
         sourceId: source.id,
         budgetMs: args.fullRefresh === true ? 25_000 : 6_000,
         throwConnectionErrors: true,
+        throwUnexpectedErrors: true,
+      }).catch((error: unknown) => {
+        // A sync that fails may have written rows first, and it stores the
+        // problem on the link, so readers hear about it either way.
+        try {
+          announceGitHubSyncChange(
+            database.documentId,
+            getRequestUserEmail() ?? null,
+          );
+        } catch (announceError) {
+          // The caller still gets the sync's error; other tabs catch up on their next read.
+          console.warn(
+            "[github-source] change event failed:",
+            announceError instanceof Error
+              ? announceError.message
+              : String(announceError),
+          );
+        }
+        throw error;
       });
       githubSummary = githubSyncSummary(source.sourceName, result);
-      githubChanged = githubSyncChangedRows(result);
+      // The rows are written by now, so a status that can't be read back
+      // counts as changed rather than failing the refresh.
+      // coercion-ok: null differs from every reading, so readers look again.
+      const shownAfter = await readGitHubStatusShown(source.id).catch(
+        () => null,
+      );
+      githubChanged =
+        githubSyncChangedRows(result) ||
+        (result.state !== "busy" && shownAfter !== shownBefore);
     } else if (source.sourceType === "mock-local") {
       await resyncMockSourceSnapshot({ database, source, now });
     } else if (source.sourceType === "builder-cms") {
@@ -182,8 +215,8 @@ export default defineAction({
       ...(source.sourceType === "github" ? { githubChanged } : {}),
     };
   },
-  // A GitHub sync that changed rows changed them for everyone reading the
-  // collection, as with Sync now.
+  // A GitHub sync that changed rows or the status line changed them for
+  // everyone reading the collection, as with Sync now.
   changeResource: (_input, result) =>
     result.githubChanged
       ? documentChangeResource(result.database.documentId)

package/corpus/templates/content/actions/sync-github-folder.ts

@@ -8,7 +8,10 @@ import {
   getContentDatabaseSourceSnapshot,
   resolveDatabaseForSourceMutation,
 } from "./_database-source-utils.js";
-import { githubSyncChangedRows } from "./_github-source-freshness.js";
+import {
+  githubSyncChangedRows,
+  readGitHubStatusShown,
+} from "./_github-source-freshness.js";
 import {
   githubSyncSummary,
   readLinkedGitHubSource,
@@ -64,12 +67,23 @@ export default defineAction({
         { errorCode: "NOT_GITHUB_LINKED", statusCode: 409 },
       );
     }
+    const shownBefore = await readGitHubStatusShown(linked.id);
     const sync = await syncGitHubSource({
       sourceId: linked.id,
       budgetMs: SYNC_BUDGET_MS,
     });
     const failed: SyncFollowUp[] = [];
-    if (sync.state !== "unchanged" && sync.state !== "busy") {
+    // A busy sync changed nothing; the run already going reports for itself.
+    // A status that can't be read back counts as changed, so readers check.
+    const statusChanged =
+      sync.state !== "busy" &&
+      (await afterSync("status_read", failed, () =>
+        readGitHubStatusShown(linked.id),
+      )) !== shownBefore;
+    if (
+      statusChanged ||
+      (sync.state !== "unchanged" && sync.state !== "busy")
+    ) {
       await afterSync("refresh_signal", failed, () =>
         writeAppState("refresh-signal", { ts: Date.now() }),
       );
@@ -80,6 +94,7 @@ export default defineAction({
     return {
       database: serializeDatabase(database),
       sync,
+      statusChanged,
       source,
       followUpFailed: failed,
       summary: [
@@ -88,16 +103,19 @@ export default defineAction({
       ].join(" "),
     };
   },
-  // Everyone reading the collection gets the synced rows, not just the caller.
+  // Everyone reading the collection gets the synced rows and status, not just
+  // the caller.
   changeResource: (_input, result) =>
-    githubSyncChangedRows(result.sync)
+    githubSyncChangedRows(result.sync) || result.statusChanged
       ? documentChangeResource(result.database.documentId)
       : null,
 });
 
-type SyncFollowUp = "refresh_signal" | "source_read";
+type SyncFollowUp = "status_read" | "refresh_signal" | "source_read";
 
 const FOLLOW_UP_FAILED: Record<SyncFollowUp, string> = {
+  status_read:
+    "Whether the link's status changed couldn't be read, so readers were told to check it again.",
   refresh_signal:
     "Other open tabs couldn't be told about the changes; they show them once they reload.",
   source_read: