@dxos/plugin-magazine 0.0.0

package/src/translations.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Type } from '@dxos/echo';
+import { type Resource } from '@dxos/react-ui';
+import { translations as formTranslations } from '@dxos/react-ui-form/translations';
+
+import { meta } from '#meta';
+import { Magazine, Subscription } from '#types';
+
+export const translations = [
+  ...formTranslations,
+  {
+    'en-US': {
+      [Type.getTypename(Subscription.Subscription)]: {
+        'typename.label': 'Feed',
+        'typename.label_zero': 'Feeds',
+        'typename.label_one': 'Feed',
+        'typename.label_other': 'Feeds',
+        'object-name.placeholder': 'New feed',
+        'add-object.label': 'Add feed',
+        'rename-object.label': 'Rename feed',
+        'delete-object.label': 'Delete feed',
+        'object-deleted.label': 'Feed deleted',
+      },
+      [Type.getTypename(Subscription.Post)]: {
+        'typename.label': 'Post',
+        'typename.label_zero': 'Posts',
+        'typename.label_one': 'Post',
+        'typename.label_other': 'Posts',
+        'post-title.placeholder': 'Untitled',
+      },
+      [Type.getTypename(Magazine.Magazine)]: {
+        'typename.label': 'Magazine',
+        'typename.label_zero': 'Magazines',
+        'typename.label_one': 'Magazine',
+        'typename.label_other': 'Magazines',
+        'object-name.placeholder': 'New magazine',
+        'add-object.label': 'Add magazine',
+        'rename-object.label': 'Rename magazine',
+        'delete-object.label': 'Delete magazine',
+        'object-deleted.label': 'Magazine deleted',
+      },
+      [meta.profile.key]: {
+        'plugin.name': 'Feed',
+        'empty-feed.message': 'No posts yet',
+        'feed-companion.label': 'Feed',
+        'sync-feed.label': 'Sync feed',
+        'sync-feed-error.title': 'Failed to sync feed',
+        'feed-sync.label': 'Feed Sync',
+        'view-trigger.label': 'View trigger',
+        'add-feed.label': 'Add feed',
+        'curate.label': 'Curate',
+        'clear-magazine.label': 'Clear (preserves starred)',
+        'refreshing-magazine.label': 'Refreshing magazine...',
+        'no-feeds.label': 'Add at least one feed first',
+        'empty-magazine.message': 'No articles yet.',
+        'curate-error.message': 'Failed to curate magazine.',
+        'clear-error.message': 'Failed to clear magazine.',
+        'refresh-content-error.message': 'Failed to refresh content.',
+        'post-companion.label': 'Post',
+        'post-title.placeholder': 'Untitled',
+        'open-original.label': 'Open original',
+        'mark-unread.label': 'Mark as unread',
+        'refresh-content.label': 'Refresh content',
+        'refresh-content-pending.label': 'Refreshing…',
+        'archive-post.label': 'Archive',
+        'unarchive-post.label': 'Unarchive',
+        'star-post.label': 'Star',
+        'unstar-post.label': 'Unstar',
+        'sort-by-date.label': 'Sort by date',
+        'sort-by-rank.label': 'Sort by rank',
+        'view-filter.label': 'Filter posts',
+        'show-archived.label': 'Show archived',
+        'only-starred.label': 'Show starred only',
+        'close.label': 'Close',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types/CreateSubscription.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Format } from '@dxos/echo';
+
+import * as Subscription from './Subscription';
+
+// Structural gates (regex / URL format), used as form-field validation and to short-circuit the network
+// effects on obviously-malformed input. Handle existence is verified implicitly by the publication lookup
+// (an unresolvable handle yields no publications, and a publication is required to submit).
+export const HandleSchema = Schema.String.pipe(
+  Schema.pattern(/^@?([\da-z-]+\.)+[a-z]{2,}$|^did:[a-z]+:[a-zA-Z0-9._%:-]+$/i),
+);
+
+export const isHandle = Schema.is(HandleSchema);
+export const isUrl = Schema.is(Format.URL);
+
+//
+// Base structs (no dynamic annotations). The capability layer (create-object.ts) applies annotation
+// closures on top — those closures reference operations/sources and so cannot live in this module.
+//
+
+export const StandardSiteCreateBase = Schema.Struct({
+  type: Schema.Literal('standard-site'),
+  handle: HandleSchema.annotations({ title: 'Handle', description: 'atproto handle, e.g. dxos.org.' }),
+  // No `name`: the feed name is taken from the selected publication (resolved by `fetchStandardSite`).
+  publication: Schema.String.annotations({ title: 'Publication', description: 'Choose a publication.' }),
+});
+
+export type StandardSiteValues = Schema.Schema.Type<typeof StandardSiteCreateBase>;
+
+export const RssCreateBase = Schema.Struct({
+  type: Schema.Literal('rss'),
+  url: Format.URL.annotations({ title: 'URL', description: 'RSS feed URL.' }),
+  name: Schema.optional(Schema.String.annotations({ title: 'Name' })),
+});
+
+export type RssValues = Schema.Schema.Type<typeof RssCreateBase>;
+
+// Input type covers both annotated union members; the union itself is built in create-object.ts after
+// annotations are applied. The switch narrows on `type` which is common to both shapes.
+export type CreateSubscriptionInput =
+  | { type: 'standard-site'; handle: string; publication: string }
+  | { type: 'rss'; url: string; name?: string };
+
+/** Normalizes a create-form union member into the stored {@link Subscription.Subscription} fields. */
+export const makeSubscriptionFromCreate = (input: CreateSubscriptionInput): Subscription.Subscription => {
+  switch (input.type) {
+    case 'standard-site':
+      // `url` stores the publication site reference (at:// or https://); sync derives the author DID
+      // from it directly — no handle stored, name resolved from the publication at sync time.
+      return Subscription.makeSubscription({ type: 'standard-site', url: input.publication });
+    case 'rss':
+      return Subscription.makeSubscription({ type: 'rss', url: input.url, name: input.name });
+  }
+};

package/src/types/FeedOperation.ts

@@ -0,0 +1,134 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Operation } from '@dxos/compute';
+import { Database, DXN, Ref, Registry } from '@dxos/echo';
+
+import { meta } from '#meta';
+
+import * as Magazine from './Magazine';
+import * as Subscription from './Subscription';
+
+const makeKey = (name: string) => DXN.make(`${meta.profile.key}.operation.${name}`);
+
+/** Fetches an RSS/Atom feed and appends new posts to the backing ECHO feed. */
+export const SyncFeed = Operation.make({
+  meta: {
+    key: makeKey('syncFeed'),
+    name: 'Sync Feed',
+    description: 'Fetches RSS/Atom feed and writes posts to the ECHO feed.',
+    icon: 'ph--arrows-clockwise--regular',
+  },
+  services: [Database.Service],
+  input: Schema.Struct({
+    feed: Ref.Ref(Subscription.Subscription),
+  }),
+  output: Schema.Void,
+}).pipe(Operation.visible);
+
+/**
+ * Fetches a Post's article page over HTTP and returns extracted plain text plus
+ * any image URLs found. Read-only; does not mutate the Post. Agent-facing tool
+ * (the surviving curation tool: the agent may call it to read a candidate's full
+ * text when title + description are insufficient to judge relevance).
+ */
+export const FetchArticleContent = Operation.make({
+  meta: {
+    key: makeKey('fetchArticleContent'),
+    name: 'Fetch Article Content',
+    description: "Fetches and extracts text + image URLs from a Post's article page.",
+    icon: 'ph--article--regular',
+  },
+  input: Schema.Struct({
+    post: Ref.Ref(Subscription.Post).annotations({
+      description: 'The Post to fetch content for. The Post must have a link.',
+    }),
+  }),
+  output: Schema.Struct({
+    text: Schema.String.annotations({ description: 'Extracted plain text from the article page.' }),
+    imageUrls: Schema.Array(Schema.String).annotations({
+      description: 'Image URLs found on the page (og:image first, then <img> src values).',
+    }),
+  }),
+  services: [Database.Service],
+});
+
+/**
+ * Fetches a Post's article page over HTTP and writes the extracted plain text
+ * and hero image URL to the source Subscription's content feed. Per-Post read/star/archive
+ * state on the Subscription is keyed by Post entity id.
+ * (the Post itself is an immutable queue item). Idempotent — skips if
+ * `content` is already set or the Post has no link. Used by the reader view
+ * to populate the full article on first open.
+ */
+export const LoadPostContent = Operation.make({
+  meta: {
+    key: makeKey('loadPostContent'),
+    name: 'Load Post Content',
+    description: 'Fetches and stores the full article content on a Post.',
+    icon: 'ph--download--regular',
+  },
+  input: Schema.Struct({
+    post: Ref.Ref(Subscription.Post).annotations({
+      description: 'The Post to load content for.',
+    }),
+    force: Schema.optional(
+      Schema.Boolean.annotations({
+        description: 'Re-fetch and append fresh content even if an entry already exists (refresh).',
+      }),
+    ),
+  }),
+  output: Schema.Void,
+});
+
+/**
+ * End-to-end magazine curation: syncs all referenced feeds (in parallel), then runs an in-memory
+ * routine (the magazine's topic instructions + the registry-resolved Magazine skill) through the
+ * agent to select matching posts, adds the selected posts mechanically, and finally enforces each
+ * feed's `keep` bound. Drives the MagazineArticle Curate button; schedulable via triggers.
+ */
+export const CurateMagazine = Operation.make({
+  meta: {
+    key: makeKey('curateMagazine'),
+    name: 'Curate Magazine',
+    description: 'Syncs feeds, selects matching posts via the magazine skill, and applies per-feed keep limits.',
+    icon: 'ph--sparkle--regular',
+  },
+  input: Schema.Struct({
+    magazine: Ref.Ref(Magazine.Magazine).annotations({
+      description: 'The Magazine to curate.',
+    }),
+  }),
+  output: Schema.Struct({
+    synced: Schema.Number.annotations({ description: 'Number of feeds successfully synced.' }),
+    curated: Schema.Number.annotations({ description: 'Number of posts added to the magazine.' }),
+  }),
+  // Database.Service for candidate collection, Registry.Service to resolve the methodology skill;
+  // sub-operations (SyncFeed, RunInstructions) resolve through the ambient Operation.Service invoker.
+  services: [Database.Service, Registry.Service],
+}).pipe(Operation.visible);
+
+/**
+ * Clears a Magazine's curated posts, preserving any that are starred. Drives the MagazineArticle
+ * Clear button.
+ */
+export const ClearMagazine = Operation.make({
+  meta: {
+    key: makeKey('clearMagazine'),
+    name: 'Clear Magazine',
+    description: "Removes a Magazine's posts, keeping any that are starred.",
+    icon: 'ph--trash--regular',
+  },
+  input: Schema.Struct({
+    magazine: Ref.Ref(Magazine.Magazine).annotations({
+      description: 'The Magazine to clear.',
+    }),
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+}).pipe(Operation.visible);

package/src/types/Magazine.test.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import { test } from 'vitest';
+
+import { Database, Feed, Tag } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
+import { EntityId } from '@dxos/keys';
+import { StateMap, TagIndex, Text } from '@dxos/schema';
+
+import * as Magazine from './Magazine';
+import * as Subscription from './Subscription';
+
+EntityId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  types: [
+    Feed.Feed,
+    Subscription.Subscription,
+    Subscription.Post,
+    Magazine.Magazine,
+    Tag.Tag,
+    Text.Text,
+    StateMap.StateMap,
+    TagIndex.TagIndex,
+  ],
+  disableLlmMemoization: true,
+});
+
+describe('Magazine', () => {
+  describe('composeInstructions', () => {
+    test('returns the default methodology when no topic is set', ({ expect }) => {
+      expect(Magazine.composeInstructions()).toBe(Magazine.DEFAULT_INSTRUCTIONS);
+      expect(Magazine.composeInstructions('   ')).toBe(Magazine.DEFAULT_INSTRUCTIONS);
+    });
+
+    test('weaves the topic in under a Topic heading', ({ expect }) => {
+      const result = Magazine.composeInstructions('Space exploration');
+      expect(result.startsWith(Magazine.DEFAULT_INSTRUCTIONS)).toBe(true);
+      expect(result).toContain('## Topic');
+      expect(result).toContain('Space exploration');
+    });
+  });
+
+  it.effect(
+    'make creates the curation routine with the magazine, seeding its instructions',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const magazine = yield* Database.add(Magazine.make({ name: 'The Cosmos', instructions: 'Astronomy news' }));
+        yield* Database.flush();
+
+        // The instructions are created with the magazine (not lazily).
+        expect(magazine.instructions).toBeDefined();
+        const instructions = yield* Database.load(magazine.instructions!);
+        expect(instructions.skills.length).toBeGreaterThan(0);
+
+        const text = yield* Database.load(instructions.text);
+        expect(text.content).toContain('## Topic');
+        expect(text.content).toContain('Astronomy news');
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/types/Magazine.ts

@@ -0,0 +1,214 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { AppAnnotation } from '@dxos/app-toolkit';
+import { Instructions, Skill } from '@dxos/compute';
+import { Annotation, DXN, Obj, Ref, Type } from '@dxos/echo';
+import { FormInlineAnnotation, FormInputAnnotation, LabelAnnotation } from '@dxos/echo/Annotation';
+import { type EntityId } from '@dxos/keys';
+import { StateMap } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import * as Subscription from './Subscription';
+
+export const SKILL_KEY = 'org.dxos.skill.magazine';
+
+/**
+ * Default editorial methodology seeded into a Magazine's curation Routine. Describes WHAT to curate
+ * (selection, dedup, snippet, hero image). The HOW (candidate input shape, tool usage, output
+ * contract) lives in the Magazine skill, not here.
+ */
+export const DEFAULT_INSTRUCTIONS = trim`
+  You curate articles for a Magazine around the Topic described below.
+
+  Select only candidates that clearly match the Topic — quality over quantity.
+
+  Never select duplicate articles. Two candidates are duplicates if they share a link or guid, or if
+  their titles and content describe the same story (e.g. the same article syndicated by different
+  feeds). Keep only one of each — prefer the most complete or authoritative source — and skip the rest.
+
+  For each candidate you select, also produce:
+  - A concise 1-2 sentence snippet (plain text, no markdown) capturing why the article is relevant to
+    the Topic. If you read the full article, use it to write a richer snippet.
+  - The best hero image URL for the article, when one is available.
+`;
+
+/** Per-Post magazine-scoped curation state, keyed by Post id. */
+export const PostState = Schema.Struct({
+  /** Agent-assigned relevance within this magazine (lower = more relevant). */
+  rank: Schema.optional(Schema.Number),
+  /** Agent-written concise snippet summarising the article in the context of this magazine's topic. */
+  snippet: Schema.optional(Schema.String),
+  /** Agent-selected hero image URL for this post in this magazine. */
+  imageUrl: Schema.optional(Schema.String),
+});
+export type PostState = Schema.Schema.Type<typeof PostState>;
+
+/**
+ * Structured output contract of the curation Routine: the Posts the agent selected, each with
+ * agent-generated display values. Declared as the Routine's `output` ({@link make}) so the agent's
+ * `completeJob` carries this payload (a Void/Unknown default would silently drop it); {@link
+ * CurateMagazine} decodes the Routine result against the same schema.
+ */
+export const CurationOutput = Schema.Struct({
+  posts: Schema.Array(
+    Schema.Struct({
+      id: Obj.ID,
+      /** Concise 1-2 sentence snippet summarising why this article is relevant to the magazine topic. */
+      snippet: Schema.optional(Schema.String),
+      /** Best image URL found for this article (from the post or fetched content). */
+      imageUrl: Schema.optional(Schema.String),
+    }),
+  ),
+});
+
+/**
+ * An agent-curated collection of articles drawn from one or more Feeds.
+ * Curation is driven by a {@link Routine.Routine} created with the magazine ({@link make}): its
+ * instructions hold the editorial brief and it references the Magazine skill (the tool/output
+ * contract). {@link CurateMagazine} runs the Routine to select matching Posts.
+ */
+export class Magazine extends Type.makeObject<Magazine>(DXN.make('org.dxos.type.magazine', '0.2.0'))(
+  Schema.Struct({
+    /** User-facing title of the magazine. */
+    name: Schema.String.pipe(Schema.optional),
+    /** Feeds to pull content from. */
+    feeds: Schema.Array(Ref.Ref(Subscription.Subscription)),
+    /** Curated Post refs (insertion order; UI displays newest-last reversed). */
+    posts: Schema.Array(Ref.Ref(Subscription.Post)).pipe(FormInputAnnotation.set(false)),
+    /**
+     * Curation Instructions, created with the magazine ({@link make}). Holds the editorial brief and
+     * references the Magazine skill. Rendered inline by the properties form (the Instructions'
+     * own fields), so the brief is edited there without a custom surface.
+     * Optional for backward compatibility; {@link CurateMagazine} and the toolbar require it.
+     */
+    instructions: Ref.Ref(Instructions.Instructions).pipe(FormInlineAnnotation.set(true), Schema.optional),
+    /**
+     * Per-Post magazine-scoped curation state, keyed by Post id. Shared per-Post state (readAt,
+     * star/archive tags) lives on `Subscription`; snippet/imageUrl here are agent-written at
+     * curation time and take precedence over the RSS-derived defaults in display.
+     */
+    postState: Ref.Ref(StateMap.StateMap).pipe(FormInputAnnotation.set(false)),
+    /**
+     * Maximum number of (non-starred) curated Posts retained on the magazine after curation.
+     * Older posts beyond this bound are dropped; starred posts are preserved regardless.
+     * Defaults to {@link Subscription.DEFAULT_KEEP} when unset.
+     */
+    keep: Schema.Number.pipe(
+      Schema.annotations({
+        title: 'Keep',
+        description: 'Number of items to keep.',
+      }),
+      Schema.optional,
+    ),
+  }).pipe(
+    LabelAnnotation.set(['name']),
+    Annotation.IconAnnotation.set({ icon: 'ph--book-open-text--regular', hue: 'indigo' }),
+    AppAnnotation.SkillsAnnotation.set([SKILL_KEY]),
+  ),
+) {}
+
+/** Checks if a value is a Magazine object. */
+export const instanceOf = (value: unknown): value is Magazine => Obj.instanceOf(Magazine, value);
+
+export type MakeProps = Omit<Obj.MakeProps<typeof Magazine>, 'feeds' | 'posts' | 'instructions' | 'postState'> & {
+  feeds?: Ref.Ref<Subscription.Subscription>[];
+  posts?: Ref.Ref<Subscription.Post>[];
+  /** Editorial brief seeded into the curation Routine's instructions (composed with the default methodology). */
+  instructions?: string;
+};
+
+/**
+ * Creates a Magazine plus its curation Routine and per-Post state map as hidden children (all
+ * cascade-deleted with the magazine). The Routine holds the editorial brief (its instructions,
+ * seeded from {@link composeInstructions}) and references the Magazine skill by its registry DXN;
+ * {@link CurateMagazine} runs it and the agent resolves the skill at run time.
+ */
+export const make = (props: MakeProps = {}): Magazine => {
+  const postState = StateMap.make();
+  const magazine = Obj.make(Magazine, {
+    name: props.name,
+    feeds: props.feeds ?? [],
+    posts: props.posts ?? [],
+    keep: props.keep,
+    postState: Ref.make(postState),
+  });
+
+  const instructions = Instructions.make({
+    name: props.name ? `${props.name} curation` : 'Magazine curation',
+    text: composeInstructions(props.instructions),
+    skills: [Ref.fromURI(Skill.registryURI(SKILL_KEY))],
+    // Bind the magazine as session context so the agent sees it, not only the candidate JSON input.
+    objects: [Ref.make(magazine)],
+    // Declare the selection contract so the agent's completeJob carries the chosen Posts.
+    output: CurationOutput,
+  });
+  Obj.update(magazine, (magazine) => {
+    magazine.instructions = Ref.make(instructions);
+  });
+
+  // Cascade-delete the Instructions object (and its Text) and the per-Post state with the magazine.
+  Obj.setParent(instructions, magazine);
+  if (instructions.text.target) {
+    Obj.setParent(instructions.text.target, instructions);
+  }
+  Obj.setParent(postState, magazine);
+  return magazine;
+};
+
+/** Composes Routine instructions from the default editorial methodology and an optional topic focus. */
+export const composeInstructions = (topic?: string): string => {
+  const trimmed = topic?.trim();
+  return trimmed ? `${DEFAULT_INSTRUCTIONS}\n\n## Topic\n\n${trimmed}` : DEFAULT_INSTRUCTIONS;
+};
+
+/** Schema for the create-magazine dialog form. */
+export const CreateMagazineSchema = Schema.Struct({
+  name: Schema.optional(
+    Schema.String.annotations({
+      title: 'Name',
+    }),
+  ),
+  feeds: Schema.Array(Ref.Ref(Subscription.Subscription)).annotations({
+    title: 'Feeds',
+  }),
+  instructions: Schema.optional(
+    Schema.String.annotations({
+      title: 'Topic',
+      description: 'Describe what content to curate.',
+    }),
+  ),
+});
+
+//
+// Per-Post magazine-scoped curation state, keyed by Post id.
+//
+
+/** Agent-assigned relevance of a Post within a Magazine, or undefined. */
+export const getRank = (magazine: Magazine | undefined, postId: EntityId): number | undefined => {
+  const stateMap = magazine?.postState.target;
+  return stateMap ? StateMap.bind<PostState>(stateMap).get(postId).rank : undefined;
+};
+
+/** Returns the full magazine-scoped {@link PostState} for a Post, or an empty record. */
+export const getPostState = (magazine: Magazine | undefined, postId: EntityId): Partial<PostState> => {
+  const stateMap = magazine?.postState.target;
+  return stateMap ? StateMap.bind<PostState>(stateMap).get(postId) : {};
+};
+
+/** Merges partial state into a Post's magazine-scoped {@link PostState}. */
+export const patchPostState = (magazine: Magazine, postId: EntityId, state: Partial<PostState>): void => {
+  const stateMap = magazine.postState.target;
+  if (stateMap) {
+    StateMap.bind<PostState>(stateMap).patch(postId, state);
+  }
+};
+
+/** Sets the magazine-scoped rank for a Post. */
+export const setRank = (magazine: Magazine, postId: EntityId, rank: number): void =>
+  patchPostState(magazine, postId, { rank });