astro-atmosphere-publishing 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0 (8 November 2026)
+
+- **Posts you've already announced keep their announcement.** `announcement:` in a post's frontmatter (an AT URI or a bsky.app address) names a Bluesky post that already announces it, made by hand, by a release bot or by another tool. The post is never announced again: its record points to that post (`bskyPostRef`), so comments, likes and reposts carry on in the same thread. A collection's `announcement` function maps a field of your own instead (`(post) => post.data.bskyPost`).
+- The preview lists these as "linked to existing announcement". A post that's by another account, deleted or mistyped is reported as a problem for that post only, and everything else carries on. `announce:` and `announcement:` on the same post is an error.
+- Naming a different post later moves the record to it, and nothing is deleted on Bluesky. The preview notes posts that share one announcement.
+- Nothing changes for existing sites: no state file change, and no records are rewritten.
+
 ## 0.1.1 (7 November 2026)
 
 - **@mentions, #hashtags and links in announcements work**, as in the Bluesky app: they become links, and mentioned accounts are notified. The preview lists what each announcement will link.

package/README.md

@@ -114,6 +114,21 @@ Set it for the whole site (`share` in the settings), a collection, or one post (
 - @mentions, #hashtags and links in the wording work as in the Bluesky app: they become links, and mentioned accounts are notified. The preview lists what each announcement will link.
 - Each post is announced once.
 
+### Posts you've already announced
+
+Posts announced on Bluesky before your site used this package (by hand, by a release bot or by another tool) can keep that announcement, and the comments, likes and reposts on it. Name it in the post's frontmatter, as an AT URI or a bsky.app address:
+
+```yaml
+announcement: "https://bsky.app/profile/example.com/post/3kbbgdr267n2b"
+```
+
+The post is never announced again. Instead its record points to that post (`bskyPostRef`), so Atmosphere Comments shows that thread under the article. The preview lists it as "linked to existing announcement".
+
+- The announcement must be by your publishing account. A post that's by another account, deleted or mistyped is reported in the preview, and published without an announcement (or keeps the one it had), while everything else carries on.
+- A post can't have both `announce:` and `announcement:`: one makes a new announcement, the other uses one you already made.
+- Naming a different post later moves the record to it. Nothing is ever deleted on Bluesky.
+- If your posts already keep the address in a field of their own, map it in the collection rather than renaming it: `announcement: (post) => post.data.bskyPost`.
+
 ## With Atmosphere Comments for Astro
 
 Comments find each post's announcement through its `<link>` tag, so the comment box needs no `post` prop. For the Subscribe button, hand the publication over in one line:
@@ -174,7 +189,7 @@ Commit the state file even when publishing fails part-way: it's saved after ever
 | `site` | required | Your site's address. |
 | `account` | required | The publishing account's DID. |
 | `publication.name`, `.description`, `.icon` | name required | The publication record. |
-| `collections` | required | One or more: `files` (a glob) and `path` (a function), plus optional overrides: `id`, `title`, `description`, `share`, `textContent`, `tags`, `publishedAt`, `updatedAt`, `cover`, `draft` and `archived` (posts never treated as new, such as ones imported from an old site). Each takes the post (`id`, `file`, `folder`, `data` for the frontmatter, `body`). |
+| `collections` | required | One or more: `files` (a glob) and `path` (a function), plus optional overrides: `id`, `title`, `description`, `share`, `textContent`, `tags`, `publishedAt`, `updatedAt`, `cover`, `draft`, `archived` (posts never treated as new, such as ones imported from an old site) and `announcement` (a Bluesky post that already announces the post; see "Posts you've already announced"). Each takes the post (`id`, `file`, `folder`, `data` for the frontmatter, `body`). |
 | `share` | default `"more"` | How much of each post goes into its record (see "How much of each post is shared"). |
 | `announceWithinDays` | default 14 | How recent a post must be to count as new. |
 | `langs` | default `["en"]` | The announcements' languages. |

package/bin/cli.mjs

@@ -9,7 +9,7 @@
 // there is read too, if present.
 import { existsSync } from "node:fs";
 import { loadConfig } from "../lib/config.mjs";
-import { describe, linkedFor, plan, publish } from "../lib/publish.mjs";
+import { describe, isNotice, linkedFor, plan, publish } from "../lib/publish.mjs";
 import { publicAgent, reader } from "../lib/account.mjs";
 import { saveState } from "../lib/state.mjs";
 import { syncState } from "../lib/sync.mjs";
@@ -23,7 +23,7 @@ async function main() {
   if (command === "preview") {
     const result = await plan(config);
     const lines = describe(result, config, undefined, await linkedFor(result, publicAgent()));
-    if (!lines.some((line) => !line.startsWith("note:"))) {
+    if (!lines.some((line) => !isNotice(line))) {
       for (const line of lines) console.log(`  • ${line}`);
       console.log("Everything is already published and up to date.");
       return;

package/index.d.ts

@@ -38,6 +38,12 @@ export type CollectionSettings = {
   draft?: (post: Entry) => boolean;
   /** Posts that are never "new" (imported from an old site, say), so they're only announced when they ask. */
   archived?: (post: Entry) => boolean;
+  /**
+   * A Bluesky post that already announces this post (an AT URI or a bsky.app
+   * address), made by hand or another tool. The post is linked to it and never
+   * announced again. Default: the frontmatter's `announcement`.
+   */
+  announcement?: (post: Entry) => string | undefined;
 };
 
 export type Share = "more" | "intro" | "full" | "none";

package/lib/entries.mjs

@@ -43,6 +43,14 @@ export async function readEntries(config) {
       const share = entry.data.share ?? collection.share ?? config.share;
       if (!SHARE_OPTIONS.includes(share)) throw new Error(`${relative}: share must be one of ${SHARE_OPTIONS.join(", ")}.`);
       const cover = (collection.cover ?? ((e) => e.data.heroImage ?? e.data.cover ?? e.data.image))(entry);
+      // An existing Bluesky post to link as the announcement (lib/existing.mjs).
+      const announcement = (collection.announcement ?? ((e) => e.data.announcement))(entry) || undefined;
+      if (announcement !== undefined && entry.data.announce !== undefined) {
+        throw new Error(
+          `${relative}: has both announce: and an existing announcement (${announcement}). ` +
+            "Keep announcement: to link the post you already made, or announce: to make a new one, not both.",
+        );
+      }
       // The field order matters: it is part of each record's fingerprint.
       posts.push({
         id: entry.id,
@@ -58,6 +66,7 @@ export async function readEntries(config) {
         coverFile: typeof cover === "string" ? path.resolve(entry.folder, cover) : null,
         archived: Boolean(collection.archived?.(entry)),
         announce: entry.data.announce,
+        announcement,
         source: relative,
       });
     }

package/lib/existing.mjs

@@ -0,0 +1,80 @@
+// Posts announced before the site used this package (by hand, by a release bot
+// or by another tool) can name that Bluesky post as their announcement, with
+// `announcement:` in their frontmatter (an AT URI or a bsky.app address). It is
+// never announced again: the post is linked to it, so its record points to that
+// thread (`bskyPostRef`) and comments, likes and reposts carry on there.
+const POST = "app.bsky.feed.post";
+const AT_URI = /^at:\/\/([^/]+)\/app\.bsky\.feed\.post\/([a-zA-Z0-9._:~-]+)$/;
+const BSKY_URL = /^https:\/\/bsky\.app\/profile\/([^/]+)\/post\/([a-zA-Z0-9._:~-]+)\/?$/;
+
+/** The repo (DID or handle) and record key of an AT URI or bsky.app post address, or null. */
+export function parseAnnouncement(value) {
+  const text = String(value).trim();
+  const match = text.match(AT_URI) ?? text.match(BSKY_URL);
+  return match ? { repo: decodeURIComponent(match[1]), rkey: match[2] } : null;
+}
+
+/** True when the stored announcement is already the one the post names, so nothing needs looking up. */
+function alreadyLinked(value, stored) {
+  if (!stored) return false;
+  const text = String(value).trim().replace(/\/+$/, "");
+  return text === stored.uri || text === stored.url;
+}
+
+/**
+ * Looks up every post's `announcement:` that isn't already linked, through
+ * Bluesky's public service. Returns, by post id, either `{ link }` (the
+ * announcement to store: `uri`, `cid`, `url`) or `{ problem }` (why that post
+ * can't be linked; the rest of the run carries on).
+ */
+export async function resolveExisting(posts, state, config, agent) {
+  const found = {};
+  const wanted = [];
+  for (const post of posts) {
+    if (post.announcement === undefined || post.announcement === null || post.announcement === "") continue;
+    if (alreadyLinked(post.announcement, state.announcements[post.id])) continue;
+    const parsed = parseAnnouncement(post.announcement);
+    if (!parsed) {
+      found[post.id] = { problem: `announcement: "${post.announcement}" isn't a Bluesky post's address (at://… or https://bsky.app/profile/…/post/…)` };
+      continue;
+    }
+    wanted.push({ post, ...parsed });
+  }
+  if (!wanted.length) return found;
+
+  // Handles in bsky.app addresses become DIDs.
+  const dids = new Map();
+  for (const { repo } of wanted) {
+    if (repo.startsWith("did:") || dids.has(repo)) continue;
+    try {
+      dids.set(repo, (await agent.resolveHandle({ handle: repo })).data.did);
+    } catch {
+      dids.set(repo, null);
+    }
+  }
+  const uriOf = ({ repo, rkey }) => {
+    const did = repo.startsWith("did:") ? repo : dids.get(repo);
+    return did ? `at://${did}/${POST}/${rkey}` : null;
+  };
+
+  const uris = [...new Set(wanted.map(uriOf).filter(Boolean))];
+  const fetched = new Map();
+  for (let start = 0; start < uris.length; start += 25) {
+    const { data } = await agent.app.bsky.feed.getPosts({ uris: uris.slice(start, start + 25) });
+    for (const item of data.posts) fetched.set(item.uri, item);
+  }
+
+  for (const entry of wanted) {
+    const { post, repo } = entry;
+    const uri = uriOf(entry);
+    const item = uri && fetched.get(uri);
+    if (!uri) found[post.id] = { problem: `announcement: couldn't find the account @${repo}` };
+    else if (!item) found[post.id] = { problem: `announcement: ${post.announcement} doesn't exist (deleted, or the address is wrong)` };
+    else if (item.author.did !== config.account) {
+      found[post.id] = { problem: `announcement: ${post.announcement} is by @${item.author.handle}, not the publishing account (${config.account})` };
+    } else {
+      found[post.id] = { link: { uri: item.uri, cid: item.cid, url: `https://bsky.app/profile/${item.author.handle}/post/${entry.rkey}` } };
+    }
+  }
+  return found;
+}

package/lib/publish.mjs

@@ -6,6 +6,7 @@ import { STANDARD_SITE, isEmpty, readState, saveState } from "./state.mjs";
 import { RichText } from "@atproto/api";
 import { publicAgent, signIn } from "./account.mjs";
 import { syncState } from "./sync.mjs";
+import { resolveExisting } from "./existing.mjs";
 import {
   DOCUMENT,
   PUBLICATION,
@@ -60,37 +61,66 @@ export const isNew = (post, config) =>
 export const announcementDate = (post, config) => (isNew(post, config) ? new Date() : post.publishedAt);
 
 export function wantsAnnouncement(post, state, config) {
+  // A post that names an existing announcement is linked to it, never announced.
+  if (post.announcement !== undefined) return false;
   if (post.announce === false) return false;
   if (state.announcements[post.id]) return false;
   if (post.announce !== undefined) return true;
   return isNew(post, config);
 }
 
-/** What would change, without changing anything. */
-export async function plan(config, state = readState(config.stateFile)) {
+/** Lines that only inform, rather than list something to publish. */
+export const isNotice = (line) => line.startsWith("note:") || line.startsWith("problem:");
+
+/**
+ * What would change, without changing anything. `agent` looks up posts that
+ * name an existing announcement (Bluesky's public service will do).
+ */
+export async function plan(config, state = readState(config.stateFile), agent = publicAgent()) {
   const posts = await readEntries(config);
+  const existing = await resolveExisting(posts, state, config, agent);
   const site = state.formats[STANDARD_SITE];
   const pubHash = await publicationHash(config);
   const publicationChange = !site.publication ? "create" : site.publication.hash !== pubHash ? "update" : null;
   const changes = [];
+  const problems = [];
   for (const post of posts) {
-    const existing = site.documents[post.id];
+    const document = site.documents[post.id];
     const announce = wantsAnnouncement(post, state, config);
-    const hash = await documentHash(post, site.publication?.uri ?? "", state.announcements[post.id] ?? null);
-    if (!existing) changes.push({ post, action: "create", announce });
-    else if (announce || existing.hash !== hash) changes.push({ post, action: "update", announce });
+    // A newly named existing announcement replaces what's stored; one that
+    // can't be used leaves the stored one (if any) as it is.
+    const { link, problem } = existing[post.id] ?? {};
+    if (problem) problems.push({ post, problem });
+    const announcement = link ?? state.announcements[post.id] ?? null;
+    const hash = await documentHash(post, site.publication?.uri ?? "", announcement);
+    if (!document) changes.push({ post, action: "create", announce, link });
+    else if (announce || link || document.hash !== hash) changes.push({ post, action: "update", announce, link });
   }
   const known = new Set(posts.map((post) => post.id));
   const orphans = Object.keys(site.documents).filter((id) => !known.has(id));
-  return { posts, state, pubHash, publicationChange, changes, orphans };
+  // Posts linked to the same announcement, which is allowed but usually a slip.
+  const byUri = new Map();
+  for (const post of posts) {
+    const uri = (existing[post.id]?.link ?? state.announcements[post.id])?.uri;
+    if (uri) byUri.set(uri, [...(byUri.get(uri) ?? []), post.id]);
+  }
+  const shared = [...byUri].filter(([, ids]) => ids.length > 1);
+  return { posts, state, pubHash, publicationChange, changes, problems, shared, orphans };
 }
 
 /** The plan in plain words, as the preview prints it. `linked` lists, by post id, what each announcement will link. */
 export function describe(result, config, handle, linked = {}) {
   const lines = [];
   if (result.publicationChange) lines.push(`${result.publicationChange} the publication record (${config.site})`);
-  for (const { post, action, announce } of result.changes) {
+  for (const { post, action, announce, link } of result.changes) {
     lines.push(`${action} the document for ${post.path}`);
+    if (link) {
+      const previous = result.state.announcements[post.id];
+      lines.push(
+        `linked to existing announcement: ${link.url}` +
+          (previous ? ` (was ${previous.url}; nothing is deleted on Bluesky)` : " (not announced again)"),
+      );
+    }
     if (!announce) continue;
     const text = announcementText(post);
     lines.push(
@@ -107,6 +137,15 @@ export function describe(result, config, handle, linked = {}) {
         "    announce: false  skips the announcement.",
     );
   }
+  for (const { post, problem } of result.problems) {
+    const kept = result.state.announcements[post.id];
+    lines.push(
+      `problem: ${post.source}: ${problem}. ` +
+        (kept ? `It keeps its current announcement (${kept.url})` : "Its record is published without an announcement") +
+        "; everything else carries on.",
+    );
+  }
+  for (const [uri, ids] of result.shared) lines.push(`note: ${ids.join(" and ")} have the same announcement (${uri}), so they share one comment thread`);
   for (const id of result.orphans) lines.push(`note: ${id} has a record but no post (or is now a draft); it was left alone`);
   return lines;
 }
@@ -131,9 +170,9 @@ export async function publish(config, log = console.log) {
     state = await syncState(config, agent, log);
     await saveState(config.stateFile, state);
   }
-  const result = await plan(config, state);
+  const result = await plan(config, state, agent);
   const lines = describe(result, config, agent.session.handle, await linkedFor(result, agent));
-  if (!lines.some((line) => !line.startsWith("note:"))) {
+  if (!lines.some((line) => !isNotice(line))) {
     for (const line of lines) log(`  • ${line}`);
     log("Everything is already published and up to date.");
     return result;
@@ -160,7 +199,13 @@ export async function publish(config, log = console.log) {
   const publicationUri = site.publication.uri;
 
   // Announcing first, so the document record can point at the Bluesky thread.
-  for (const { post, announce } of result.changes) {
+  for (const { post, announce, link } of result.changes) {
+    if (link) {
+      // Stored exactly as if it had been announced here.
+      state.announcements[post.id] = link;
+      await saveState(config.stateFile, state);
+      log(`  ✓ linked to existing announcement: ${link.url}`);
+    }
     const cover = post.coverFile ? await upload(await coverImage(post.coverFile), "image/jpeg") : undefined;
     if (announce) {
       const rich = await richTextOf(announcementText(post), agent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-atmosphere-publishing",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Publish your Astro site to the Atmosphere with Standard.site: records for every post, Bluesky announcements, and the tags that connect each page to them. Pairs with Atmosphere Comments for Astro.",
   "type": "module",
   "license": "MIT",