open_blog 0.1.0

data/lib/open_blog/write_post.rb

@@ -0,0 +1,205 @@
+module OpenBlog
+  class WritePost
+    def self.call(attributes, post:, actor:, now:, publish:, authorize: nil)
+      attributes = PostAttributes.normalize(attributes)
+      attributes = attributes.except(:external_id) if post&.persisted?
+      source = post&.persisted? ? Post.find(post.id) : PostIdentity.resolve(attributes, post: post)
+      authorize&.call(source)
+      image_inputs = ImageResolution.prepare_inputs(attributes)
+      images = ImageResolution.prepare(attributes: attributes, post: source)
+      context = {}
+      Operation.run(post: post, attributes: attributes, actor: actor, now: now, context: context, authorize: authorize) do |current, created|
+        old_slug, was_public = current.slug, current.published?
+        context[:author_default_used] = created && !attributes.key?(:author)
+        approval = attributes[:approval]
+        context[:approval_incomplete] = approval.is_a?(Hash) && approval.with_indifferent_access[:facts_checked] == false
+        release = publish == :preserve ? current.published? : publish
+        records = RedirectTarget.synchronize do
+          new(current, attributes, actor: actor, now: now, publish: release, images: images, image_inputs: image_inputs).call
+        end
+        context[:slug_changed] = was_public && old_slug != current.slug
+        records
+      end
+    rescue Error => error
+      Operation.failure(post, error)
+    rescue ActiveRecord::RecordNotFound
+      Operation.failure(post, Error::NotFound.new)
+    end
+
+    def initialize(post, attributes, actor:, now:, publish:, images:, image_inputs: {})
+      @post, @attributes, @actor, @now, @publish = post, attributes, actor, now, publish
+      @scheduled_release = publish == :scheduled
+      @images, @image_inputs = images, image_inputs
+    end
+
+    def call
+      raise Error::PostIsPublic if !@publish && @post.published?
+      old_path = @post.path if @post.persisted?
+      was_public = @post.published?
+      previous_schedule = @post.publish_at
+      PostAttributes.assign(@post, @attributes.except(*@image_inputs.keys), actor: @actor, now: @now)
+      @image_inputs.each { |field, prepared| @post.public_send("#{field}=", prepared.image) }
+      PostIdentity.resolve({ slug: @post.slug }, post: @post)
+      apply_status
+      validate_records
+      @image_inputs.each { |field, prepared| @post.public_send("#{field}=", prepared.persist(uploaded_by: @actor)) }
+      @images.materialize(@post, actor: @actor)
+      @post.send(:compute_derived)
+      validate_approval
+      validate_change
+      enforce_gates if @publish && !cancel_schedule?
+      @images.preview(@post)
+      @post.send(:compute_derived)
+      validate_approval
+      validate_change
+      enforce_approval_gate if @publish && !cancel_schedule?
+      @post.release_context = { actor: @actor, now: @now, change: @attributes[:change],
+        note: @attributes[:note], description: @attributes[:change_description], made_by_ai: @attributes[:made_by_ai] }
+      @post.save!
+      records = @post.release_records || { revision: nil, publication: nil, approval: nil }
+      store_approval(records) if @attributes.key?(:approval)
+      store_connections if @attributes.key?(:connections)
+      update_redirects(old_path, was_public)
+      enqueue if @post.scheduled? && previous_schedule != @post.publish_at
+      records
+    ensure
+      @post.release_context = nil
+    end
+
+    private
+
+    def cancel_schedule?
+      @cancel_schedule
+    end
+
+    def apply_status
+      @cancel_schedule = @post.scheduled? && @attributes.key?(:publish_at) && @attributes[:publish_at].nil?
+      if @attributes.key?(:publish_at)
+        value = @attributes[:publish_at]
+        time = value.is_a?(String) ? Time.zone.parse(value) : value
+        unless value.nil? || time.respond_to?(:to_time)
+          raise Error::ValidationFailed.new(details: [ "publish_at" ])
+        end
+        @post.publish_at = time
+      end
+      if @cancel_schedule
+        @post.status = "draft"
+      elsif @post.publish_at && @attributes.key?(:publish_at) && @post.publish_at > @now
+        raise Error::ValidationFailed.new(details: [ "publish_at" ]) unless @publish || @post.scheduled?
+        @post.status = "scheduled"
+      elsif @publish
+        @post.status = "published"
+        @post.publish_at = nil
+      end
+    rescue ArgumentError, TypeError
+      raise Error::ValidationFailed.new(details: [ "publish_at" ])
+    end
+
+    def validate_records
+      if @attributes.key?(:change) && !%w[substantive correction maintenance].include?(@attributes[:change].to_s)
+        raise Error::ValidationFailed.new(details: [ "change" ])
+      end
+      if @attributes[:change].to_s == "correction" && @attributes[:note].blank?
+        raise Error::CorrectionNoteRequired
+      end
+      if @attributes.key?(:made_by_ai) && ![ true, false, nil ].include?(@attributes[:made_by_ai])
+        raise Error::ValidationFailed.new(details: [ "made_by_ai" ])
+      end
+    end
+
+    def validate_approval
+      return unless @attributes.key?(:approval)
+      value = @attributes[:approval]
+      unless value.is_a?(Hash)
+        raise Error::ApprovalIncomplete
+      end
+      @approval = value.symbolize_keys
+      unless @approval[:name].is_a?(String) && @approval[:name].present? && [ true, false ].include?(@approval[:facts_checked])
+        raise Error::ApprovalIncomplete
+      end
+      if @approval.key?(:revision_identifier) && @approval[:revision_identifier] != @post.current_revision_identifier
+        raise Error::RevisionMismatch
+      end
+    end
+
+    def validate_change
+      return if @scheduled_release
+      return unless @publish && @post.published? && @post.public_revision
+      if @post.public_revision.identifier != @post.current_revision_identifier && @attributes[:change].blank?
+        raise Error::ChangeTypeRequired
+      end
+    end
+
+    def enforce_gates
+      enforce_approval_gate
+      messages = OpenBlog.config.before_publish&.call(@post, { actor: @actor, now: @now, attributes: @attributes })
+      raise Error::RefusedByHost.new(details: Array(messages)) if messages.present?
+    end
+
+    def enforce_approval_gate
+      return if @scheduled_release
+      if OpenBlog.config.require_approval && !@post.provenance_human_written?
+        approved = @approval && @approval[:facts_checked] == true
+        approved ||= @post.approvals.joins(:revision).exists?(facts_checked: true, open_blog_revisions: { identifier: @post.current_revision_identifier }) if @post.persisted?
+        raise Error::ApprovalRequired unless approved
+      end
+    end
+
+    def store_approval(records)
+      revision = @post.revisions.find_by(identifier: @post.current_revision_identifier)
+      if revision
+        records[:revision] ||= "same"
+      else
+        revision = @post.revisions.create!(identifier: @post.current_revision_identifier,
+          payload: RevisionPayload.new(@post).to_json, actor: @actor, made_by_ai: @attributes[:made_by_ai], created_at: @now)
+        records[:revision] = "new"
+      end
+      @post.approvals.create!(revision: revision, kind: "sent", reviewer_name: @approval[:name],
+        facts_checked: @approval[:facts_checked], approved_at: @now, recorded_by: @actor)
+      records[:approval] = "sent"
+    end
+
+    def store_connections
+      input = @attributes[:connections]
+      unless input.is_a?(Hash)
+        raise Error::ValidationFailed.new(details: [ "connections" ])
+      end
+      input = input.symbolize_keys
+      if (input.keys - %i[connections third_party_paid declared_by declared_on]).any? || ![ true, false ].include?(input[:third_party_paid])
+        raise Error::ValidationFailed.new(details: [ "connections" ])
+      end
+      if input[:connections].is_a?(Array)
+        input[:connections].each do |entry|
+          next unless entry.is_a?(Hash)
+          unknown = entry.keys.map(&:to_s) - %w[party relation]
+          raise Error::UnknownField.new(details: unknown.map { |key| "connections.connections.#{key}" }) if unknown.any?
+        end
+      end
+      input[:declared_on] = @now.to_date unless input.key?(:declared_on)
+      @post.connection_declarations.create!(**input, recorded_by: @actor, created_at: @now)
+    end
+
+    def update_redirects(old_path, was_public)
+      if old_path && old_path != @post.path && was_public
+        redirect = Redirect.find_or_initialize_by(old_path: old_path)
+        raise Error::SlugReserved if redirect.persisted? && redirect.post_id != @post.id
+        if redirect.new_record?
+          redirect.assign_attributes(post: @post, source: "slug_change", occurred_on: @now.to_date)
+        end
+        redirect.update!(new_path: @post.path)
+        Redirect.where(new_path: old_path).update_all(new_path: @post.path, updated_at: @now)
+      end
+      if @post.published?
+        Redirect.where(old_path: @post.path, post: @post).destroy_all
+        Redirect.where(post: @post, source: %w[slug_change adoption unpublish removal]).update_all(new_path: @post.path, updated_at: @now)
+      end
+    end
+
+    def enqueue
+      id, due = @post.id, @post.publish_at
+      ActiveRecord.after_all_transactions_commit do
+        PublishScheduledPostJob.set(wait_until: due).perform_later(id)
+      end
+    end
+  end
+end

data/lib/open_blog.rb

@@ -0,0 +1,91 @@
+require "json"
+require "rails"
+require "commonmarker"
+require "rouge"
+require "mcp"
+
+require_relative "open_blog/version"
+require_relative "open_blog/instructions"
+
+module OpenBlog
+  FAQ_SELECTORS = { section: "[data-open-blog-faq]", entry: "[data-open-blog-faq-entry]" }.freeze
+
+  autoload :Configuration, "open_blog/configuration"
+  autoload :ConfigurationError, "open_blog/configuration_error"
+  autoload :RevisionPayload, "open_blog/revision_payload"
+  autoload :PlainText, "open_blog/plain_text"
+  autoload :Result, "open_blog/result"
+  autoload :Error, "open_blog/errors"
+  autoload :PostIdentity, "open_blog/post_identity"
+  autoload :PostAttributes, "open_blog/post_attributes"
+  autoload :Operation, "open_blog/operation"
+  autoload :WritePost, "open_blog/write_post"
+  autoload :SaveDraft, "open_blog/save_draft"
+  autoload :Publish, "open_blog/publish"
+  autoload :Approve, "open_blog/approve"
+  autoload :RedirectTarget, "open_blog/redirect_target"
+  autoload :Remove, "open_blog/remove"
+  autoload :Unpublish, "open_blog/unpublish"
+  autoload :RecordRelease, "open_blog/record_release"
+  autoload :ContentGuard, "open_blog/content_guard"
+  autoload :RichTextGuard, "open_blog/rich_text_guard"
+  autoload :PolicyUrl, "open_blog/policy_url"
+  autoload :LabelPolicy, "open_blog/label_policy"
+  autoload :Findings, "open_blog/findings"
+  autoload :Adopt, "open_blog/adopt"
+  autoload :FaqExtraction, "open_blog/faq_extraction"
+  autoload :ImageFetch, "open_blog/image_fetch"
+  autoload :ImageImport, "open_blog/image_import"
+  autoload :ImageResolution, "open_blog/image_resolution"
+  autoload :Renderer, "open_blog/renderer"
+  autoload :SyntaxCss, "open_blog/syntax_css"
+  autoload :BuildCss, "open_blog/build_css"
+  autoload :ReaderPage, "open_blog/reader_page"
+  autoload :ReaderDates, "open_blog/reader_dates"
+  autoload :JsonFeed, "open_blog/json_feed"
+  autoload :MarkdownView, "open_blog/markdown_view"
+  autoload :ReaderQueries, "open_blog/reader_queries"
+  autoload :Search, "open_blog/search"
+  autoload :PageViews, "open_blog/page_views"
+  autoload :Pagination, "open_blog/pagination"
+  autoload :NotFound, "open_blog/not_found"
+  autoload :SitemapEntries, "open_blog/sitemap_entries"
+  autoload :SurfaceReport, "open_blog/surface_report"
+  autoload :Doctor, "open_blog/doctor"
+  autoload :Sample, "open_blog/sample"
+  autoload :Actor, "open_blog/actor"
+  autoload :Mcp, "open_blog/mcp"
+  autoload :ApiFields, "open_blog/api_fields"
+  autoload :Authentication, "open_blog/authentication"
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    def policy_url(kind, config: self.config)
+      PolicyUrl.call(kind, config: config)
+    end
+
+    def sitemap_entries(base_url: config.public_base_url)
+      SitemapEntries.call(base_url: base_url)
+    end
+
+    def mount_path
+      application = Rails.application
+      return config.mount_path unless application&.initialized?
+
+      route = application.routes.routes.find do |candidate|
+        candidate.app.respond_to?(:app) && candidate.app.app == Engine
+      end
+      route ? route.path.spec.to_s : config.mount_path
+    end
+  end
+end
+
+require_relative "open_blog/engine"

data/lib/tasks/open_blog.rake

@@ -0,0 +1,71 @@
+namespace :open_blog do
+  desc "Set up authentication during installation without replacing existing tokens"
+  task install_token: :environment do
+    if OpenBlog.config.authenticate
+      puts "API token: using host authentication."
+    elsif OpenBlog::ApiToken.exists?
+      puts "API token: existing token kept; use open_blog:token to issue another if needed."
+    else
+      _record, secret = OpenBlog::ApiToken.generate(name: "Blog publisher")
+      puts "API token: #{secret}"
+      puts "Save this secret now; it will not be shown again."
+    end
+  end
+
+  desc "Issue an API token and print its secret once"
+  task token: :environment do
+    name = ENV.fetch("NAME") { abort "Set NAME to identify this token's actor." }
+    scopes = ENV.key?("SCOPES") ? ENV.fetch("SCOPES").split(",").map(&:strip) : OpenBlog::ApiToken::SCOPES
+    expires_at = Time.iso8601(ENV.fetch("EXPIRES_AT")) if ENV["EXPIRES_AT"].present?
+    _record, secret = OpenBlog::ApiToken.generate(name: name, scopes: scopes, expires_at: expires_at)
+    puts secret
+  end
+
+  desc "Check the blog installation and report remaining setup"
+  task doctor: :environment do
+    checks = OpenBlog::Doctor.run
+    checks.each { |check| puts "#{check[:status]}: #{check[:name]} — #{check[:message]}" }
+    exit 1 if checks.any? { |check| check[:status].to_s == "error" }
+  end
+
+  desc "Create the sample article if it does not already exist"
+  task sample: :environment do
+    puts "Sample article: #{OpenBlog::Sample.call.path}"
+  end
+
+  desc "Generate scoped syntax colors for the configured light and dark theme"
+  task :syntax_css, [ :path ] => :environment do |_task, arguments|
+    puts "Wrote #{OpenBlog::SyntaxCss.write(path: arguments[:path])}"
+  end
+  desc "Build the packaged stylesheet and token-only theme override"
+  task build_css: :environment do
+    options = ENV["OUT"].present? ? { path: ENV["OUT"] } : {}
+    puts "Wrote #{OpenBlog::BuildCss.write(**options)}"
+  end
+end
+
+namespace :open_blog do
+  desc "Publish scheduled posts that are due"
+  task publish_due: :environment do
+    OpenBlog::Post.where(status: "scheduled").where("publish_at <= ?", Time.current).find_each do |post|
+      OpenBlog::PublishScheduledPostJob.perform_now(post.id)
+    end
+  end
+end
+
+namespace :open_blog do
+  desc "Delete daily view totals older than the configured retention period"
+  task prune_page_views: :environment do
+    puts "Pruned #{OpenBlog::PageViews.prune!} daily view totals"
+  end
+end
+
+namespace :open_blog do
+  desc "Inspect public pages and publishing records"
+  task report: :environment do
+    puts OpenBlog::SurfaceReport.run(scope: ENV.fetch("SCOPE", "site"), post: ENV["POST"],
+      page: ENV.fetch("PAGE", "1"), reach: ENV.fetch("REACH", "false")).to_text
+  rescue OpenBlog::Error => error
+    abort "#{error.code}: #{error.details.join(', ')}"
+  end
+end

data/skills/open-blog-adopt/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: open-blog-adopt
+description: Import existing articles into Open Blog with historical evidence, reviewed FAQ extraction, and dry runs.
+---
+
+Read the source articles without changing the source system. Preserve each exact slug, source identity, original body, and available historical records. Use `blog_extract_faq` to propose a separate FAQ list. Before applying a proposal, check that each answer is complete, the suggested cuts remove only FAQ content, the remaining body reads correctly, internal links still work, and the body does not duplicate the stored FAQ. Review ambiguous classifications with the user. Store source_body_sha256 when the submitted body differs from the original.
+
+Ask whether the original system has an approval record for the imported article. Use imported_approval only with its reviewer, original time, evidence, and the person confirming that it covers this content. Otherwise, record a declaration only when the user supplies the reviewer, approval time, facts_checked answer, declaration date, and their own name. Ask for a declared first publication date when historical evidence is missing, and place that answer in declaration.declared_first_published_at. Do not send approval in an adoption request or invent historical evidence or declarations.
+
+Use `blog_adopt_post` with dry_run true first. Inspect the proposed full article, notices, records, and redirects. A complete snapshot replaces omitted FAQ and tag lists with empty lists; send every field that must survive. Missing evidence leaves historical dates unknown. Do not assign today's date as an invented publication date.
+
+After reviewing the dry-run result, import within the user's authorized migration scope. Check article totals, slugs, redirects, images, FAQ records, and notices. Reusing a source pair updates that import only until later publishing activity makes replacement unsafe; investigate an already_changed_in_gem refusal instead of forcing it.

data/skills/open-blog-install/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: open-blog-install
+description: Install and configure Open Blog in a Rails host, customize its reader theme, and check setup.
+---
+
+Install the gem in the requested Rails application, then run `bin/rails generate open_blog:install`. Inspect the host's JavaScript, Tailwind, image processor, mount path, and authentication setup before selecting options. Use `--skip-tailwind` when the host should keep its CSS configuration; use the generated theme override for branding.
+
+Run `bin/rails open_blog:doctor` or `blog_doctor` and resolve relevant errors. Configure the actual publisher, author, public base URL, and policy links. Replace placeholders with user-supplied identities. Keep the initial API token secret; installation prints it once and repeat runs do not recover it. A host authentication hook takes precedence over tokens.
+
+Check `tools/list` before using MCP tools. Finish with an actual reader request and authenticated `blog_list_posts` call. Do not publish unrelated content, change production routing, or deploy merely because installation was requested.

data/skills/open-blog-policy-pages/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: open-blog-policy-pages
+description: Prepare accurate editorial policy pages for an Open Blog publisher from the publisher’s own answers.
+---
+
+Use `blog_doctor` to inspect policy links. Read existing pages with `blog_get_site_page`, passing `kind`: `responsible_party`, `corrections`, `editorial`, or `ai_use`. A missing page returns `not_found`; start with the publisher’s answers below.
+
+Ask for the accountable publisher and contact route, correction handling and reader reports, editorial selection and review practices, and how AI is used. Write only practices the user confirms. Reuse an existing host policy URL when that is the user's chosen source.
+
+Show the final pages for approval before publishing. Use `blog_save_site_page` with `kind`, `title`, Markdown `body`, and `status: "draft"` while preparing text. After approval, save `status: "published"` with the actual `approved_by` name and ISO date `approved_on`; this requires both write and publish scopes. Do not fill approval fields from assumptions. Verify the published links and rendered text.

data/skills/open-blog-publish/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: open-blog-publish
+description: Draft, review, publish, or schedule an Open Blog article using revision-bound approval.
+---
+
+Use `blog_search_posts` to check for existing coverage. Reuse or upload images with `blog_upload_image`; put their returned URLs in the body. Supply alternative text and keep FAQ answers as plain text.
+
+Save with `blog_save_draft`, inspect the returned findings, and correct the draft before asking for approval. Use the returned preview URL or `blog_get_preview_link` so the user sees the version being reviewed. Keep its revision identifier with the answer.
+
+Show the final text to the user before publication and ask once whether they approve that exact version and have checked its facts. Include the preview link for unpublished content. Record approval only from an actual answer: send the user's name, facts_checked with their stated true or false value, and the reviewed draft's revision_identifier. For an approved public edit without a saved draft identifier, send the complete reviewed content and inline approval with the user's name and facts_checked answer, omitting approval.revision_identifier so the operation binds it to the new revision. Never attach the old public identifier to changed text. Compare the returned content with the reviewed version and report any unexpected difference. If no answer was given, omit approval. Never invent a review or a fact-check. When text changes after approval, show the new version and ask again.
+
+Set provenance to ai_assisted if AI authored or rewrote any content, or human_written only when a person wrote all of it.
+
+Call `blog_publish_post` only within the user's publication request. Include the recorded approval when available; do not turn an unanswered fact-check question into true. A future `publish_at` schedules the post. Check the response state, notices, and findings; a schedule is not confirmation that the article is already public.

data/skills/open-blog-report/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: open-blog-report
+description: Inspect Open Blog diagnostics and available automated checks, then explain concrete findings and limits.
+---
+
+Start with `blog_doctor` for installation checks and `blog_check_post` for a particular article. Check `tools/list` before requesting broader reports. If `blog_get_surface_report` is available, request the relevant scope; opt into reach checks only when network checks fit the task.
+
+Separate observed failures, warnings, skipped checks, and matters that require a person to assess. Automated checks describe observed behavior; they cannot certify editorial practices. Explain each actionable finding using the affected page or field and propose a proportionate correction.
+
+Report only what the returned evidence supports. Do not fabricate results for unavailable tools, treat a successful HTTP response as proof of review, or silently rewrite and publish content while inspecting it.

data/skills/open-blog-update/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: open-blog-update
+description: Revise or correct a public Open Blog article while preserving its publishing history.
+---
+
+Read the current post and history with `blog_get_post` and `blog_get_post_records`. Choose substantive for a meaningful content revision, correction for an error that needs a reader-visible note, or maintenance for changes that should not advance the modification date.
+
+A public article has one content state: an update is immediately public. Present the proposed final text before calling a write tool; there is no separate preview of edits to an already-public post. Fetch the current content again if another editor may have changed it.
+
+Show the final text to the user before publication and ask once whether they approve that exact version and have checked its facts. Include the preview link for unpublished content. Record approval only from an actual answer: send the user's name, facts_checked with their stated true or false value, and the reviewed draft's revision_identifier. For an approved public edit without a saved draft identifier, send the complete reviewed content and inline approval with the user's name and facts_checked answer, omitting approval.revision_identifier so the operation binds it to the new revision. Never attach the old public identifier to changed text. Compare the returned content with the reviewed version and report any unexpected difference. If no answer was given, omit approval. Never invent a review or a fact-check. When text changes after approval, show the new version and ask again.
+
+Set provenance to ai_assisted if AI authored or rewrote any content, or human_written only when a person wrote all of it.
+
+Use `blog_update_post` with the selected change type, or `blog_correct_post` with a concrete correction note. Omitted fields remain unchanged; supplied FAQ and tag lists replace their lists. Read the returned findings and revision identifier. `blog_approve_revision` records a later review only for the current public identifier; never reuse an approval for text the reviewer did not see.
+
+Include the complete reviewed title, body, FAQ list, and image fields in the update. An inline approval without an identifier binds to the resulting revision and works when the host requires approval. Compare the returned content with the reviewed version. A separate later approval is appropriate only when publication without approval is allowed and the user has reviewed that resulting revision.