notion_publish 0.1.0

data/lib/notion_publish/commands/whoami.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module NotionPublish
+  module Commands
+    # Says what the token authenticates as, which is the first thing to check
+    # when a page cannot be reached.
+    class Whoami < Command
+      KINDS = {
+        person: "personal access token (acts as a person)",
+        bot_user: "connection owned by a user",
+        bot_workspace: "internal connection owned by the workspace"
+      }.freeze
+
+      def call
+        stdout.puts "#{client.connection_name} -- #{KINDS.fetch(client.credential_kind, 'unknown credential')}"
+        stdout.puts "  id:            #{client.me['id']}"
+        if (workspace = client.me.dig("bot", "workspace_name"))
+          stdout.puts "  workspace:     #{workspace}"
+        end
+        stdout.puts "  API version:   #{client.api_version}"
+        CLI::OK
+      end
+    end
+  end
+end

data/lib/notion_publish/commands.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "commands/command"
+require_relative "commands/adopt"
+require_relative "commands/properties"
+require_relative "commands/publish"
+require_relative "commands/relink"
+require_relative "commands/republish"
+require_relative "commands/status"
+require_relative "commands/whoami"
+
+module NotionPublish
+  # One class per subcommand. Each takes a CLI::Context and returns an exit
+  # code from #call.
+  module Commands
+  end
+end

data/lib/notion_publish/decoration.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "uploader"
+
+module NotionPublish
+  # Page icon and cover.
+  #
+  # Both are top-level fields on a page rather than properties, and both are
+  # writable at creation. Notion's own stock covers are ordinary external URLs,
+  # so a URL, a local file, or (for an icon) an emoji all work.
+  module Decoration
+    URL = %r{\Ahttps?://}i
+    # Anything with a path separator, or a leading . or ~, is meant as a file.
+    PATH = %r{\A[.~]|/}
+
+    module_function
+
+    # Validate without uploading, so a dry run can reject a bad icon or a
+    # missing file without spending a round trip or leaving an orphan upload.
+    def check!(value, kind)
+      raw = value.to_s.strip
+      return if raw.empty? || raw.match?(URL)
+
+      if raw.match?(PATH) || kind == :cover
+        expanded = File.expand_path(raw)
+        raise Error, "No such #{kind} file: #{raw}" unless File.file?(expanded)
+
+        return
+      end
+
+      raise Error, icon_message(raw) if raw.ascii_only? || raw.length > 8
+    end
+
+    def icon(value, client:)
+      raw = value.to_s.strip
+      return nil if raw.empty?
+      return external(raw) if raw.match?(URL)
+      return file_upload(raw, client, "icon") if raw.match?(PATH)
+
+      # Emoji are never ASCII. Catching that here gives a better message than
+      # Notion's for the common mistakes: a bare word, or a filename written
+      # without a path so it was not recognised as one.
+      raise Error, icon_message(raw) if raw.ascii_only? || raw.length > 8
+
+      { "type" => "emoji", "emoji" => raw }
+    end
+
+    def cover(value, client:)
+      raw = value.to_s.strip
+      return nil if raw.empty?
+      return external(raw) if raw.match?(URL)
+
+      file_upload(raw, client, "cover")
+    end
+
+    def external(url) = { "type" => "external", "external" => { "url" => url } }
+
+    def file_upload(path, client, what)
+      expanded = File.expand_path(path)
+      raise Error, "No such #{what} file: #{path}" unless File.file?(expanded)
+
+      { "type" => "file_upload", "file_upload" => { "id" => Uploader.new(client).upload(expanded) } }
+    end
+
+    def icon_message(raw)
+      <<~MSG.strip
+        #{raw.inspect} is not an emoji, a URL, or a path to a file.
+
+        An icon can be an emoji (--icon 🔒), an image URL, or a local image file
+        given with a path (--icon ./logo.png).
+      MSG
+    end
+  end
+end

data/lib/notion_publish/document.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+require_relative "errors"
+
+module NotionPublish
+  # A Markdown file, split into optional YAML front matter and a body.
+  class Document
+    FRONT_MATTER = /\A---[ \t]*\r?\n(.*?\r?\n)---[ \t]*(?:\r?\n|\z)/m
+
+    attr_reader :path, :front_matter, :body
+
+    def self.load(path)
+      raise Error, "No such file: #{path}" unless File.file?(path)
+
+      new(path, File.read(path))
+    end
+
+    def initialize(path, source)
+      @path = path
+      @front_matter, @body = split(source)
+    end
+
+    # A copy with a transformed body, keeping the path and front matter.
+    def with_body(body)
+      dup.tap { |copy| copy.body = body }
+    end
+
+    def title
+      from_front_matter = front_matter["title"]
+      return from_front_matter.to_s if from_front_matter && !from_front_matter.to_s.empty?
+
+      first_heading || File.basename(path, File.extname(path))
+    end
+
+    # Notion property values live under a "properties:" key so they can never
+    # collide with the tool's own front-matter keys.
+    def properties = front_matter["properties"]
+
+    def icon = front_matter["notion_icon"]
+    def cover = front_matter["notion_cover"]
+
+    def parent = front_matter["notion_parent"]
+    def database = front_matter["notion_database"]
+
+    protected
+
+    attr_writer :body
+
+    private
+
+    def first_heading
+      body.each_line do |line|
+        return Regexp.last_match(1).strip if line =~ /\A\#\s+(.+)/
+      end
+      nil
+    end
+
+    def split(source)
+      match = source.match(FRONT_MATTER)
+      return [{}, source] unless match
+
+      parsed = begin
+        YAML.safe_load(match[1], permitted_classes: [Date, Time], aliases: false) || {}
+      rescue Psych::Exception => e
+        raise Error, "Could not parse front matter in #{path}: #{e.message}"
+      end
+      raise Error, "Front matter in #{path} must be a YAML mapping" unless parsed.is_a?(Hash)
+
+      [parsed, match.post_match]
+    end
+  end
+end

data/lib/notion_publish/errors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module NotionPublish
+  # Base for everything this gem raises on purpose. The CLI rescues this and
+  # prints +message+ without a backtrace, so messages are user-facing prose.
+  class Error < StandardError; end
+
+  # No token was passed and none is set in the environment.
+  class MissingToken < Error
+    def initialize(var_names)
+      super(<<~MSG.strip)
+        No Notion API token found.
+
+        Set one of these environment variables:
+          #{var_names.join("\n  ")}
+
+        Create a token at https://www.notion.so/profile/integrations
+      MSG
+    end
+  end
+
+  # A --parent or --page value that contains no Notion ID.
+  class InvalidReference < Error
+    def initialize(input)
+      super(<<~MSG.strip)
+        Could not find a Notion ID in: #{input}
+
+        Expected a 32-character ID, a dashed UUID, or a Notion URL such as
+        https://www.notion.so/Some-Page-32dab123cd45803f94c2d29516bd0188
+      MSG
+    end
+  end
+
+  # A settings file or the manifest could not be read.
+  class ConfigError < Error; end
+
+  # Raised for any non-2xx response. Carries the parsed Notion error body so
+  # callers can branch on +code+ rather than parsing messages.
+  class ApiError < Error
+    attr_reader :status, :code, :notion_message, :additional_data, :request_id
+
+    def initialize(status:, body:)
+      @status = status
+      @code = body["code"]
+      @notion_message = body["message"]
+      @additional_data = body["additional_data"] || {}
+      @request_id = body["request_id"]
+      super("Notion API error #{status} (#{@code}): #{@notion_message}")
+    end
+
+    def not_found? = code == "object_not_found"
+    def unauthorized? = code == "unauthorized"
+    def restricted? = code == "restricted_resource"
+    def rate_limited? = code == "rate_limited"
+
+    # The connection that was refused, when Notion tells us.
+    def integration_id = additional_data["integration_id"]
+  end
+
+  # Still rate-limited after every retry.
+  class RateLimited < ApiError; end
+end

data/lib/notion_publish/fixups.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module NotionPublish
+  # Line-level corrections applied to a Markdown body before Notion parses it.
+  #
+  # Notion accepts CommonMark and GFM well -- tables, nesting, task lists, code
+  # fences all survive -- with one systematic exception: it does not honour soft
+  # line breaks. CommonMark treats consecutive non-blank lines as one paragraph;
+  # Notion makes a separate block out of each line. Any document wrapped at a
+  # column width therefore arrives looking double-spaced, and wrapped list items
+  # break out of their list entirely.
+  #
+  # So each run of lines that CommonMark would treat as one block is joined back
+  # into one line before sending. A space, not <br>: the wrapping is an artifact
+  # of how the file is stored, not something the author meant to be seen. Only
+  # an explicit hard break -- two trailing spaces, or a trailing backslash --
+  # becomes <br>, which is what Notion's own markdown output uses.
+  module Fixups
+    FENCE = /\A\s*(?:`{3,}|~{3,})/
+    BLANK = /\A\s*\z/
+    HEADING = /\A {0,3}\#{1,6}(?:\s|\z)/
+    THEMATIC = /\A {0,3}([-*_])(?:\s*\1){2,}\s*\z/
+    TABLE = /\A {0,3}\|/
+    HTML = /\A {0,3}</
+    INDENTED_CODE = /\A {4,}\S/
+    # An image alone on its line. Joined into the line above, it would become
+    # an image inside a sentence, which Notion cannot show.
+    IMAGE_LINE = /\A\s*!\[[^\]]*\]\([^)]*\)\s*\z/
+    QUOTE = /\A {0,3}>[ \t]?(.*)\z/
+    LIST = /\A(\s*(?:[-*+]|\d+[.)])\s+)(.*)\z/
+    HARD_BREAK = /(?: {2,}|\\)\z/
+
+    module_function
+
+    def apply(body) = join_soft_wraps(body)
+
+    # Notion consumes a leading H1 as the page title -- but only when it is the
+    # document's *only* H1. A second one anywhere (a "# Revision History" at the
+    # foot is enough) makes it keep both, and the title then appears twice: once
+    # as the page title, once as a heading. Removing it here makes the result
+    # the same either way.
+    def strip_leading_h1(body)
+      lines = body.to_s.lines
+      index = lines.index { |line| !line.match?(BLANK) }
+      return body unless index && lines[index].match?(/\A {0,3}\#(?!\#)\s/)
+
+      rest = lines[(index + 1)..] || []
+      rest.shift while rest.first&.match?(BLANK)
+      # Blank lines ahead of the title go with it.
+      rest.join
+    end
+
+    def join_soft_wraps(body)
+      out = []
+      run = nil
+      in_fence = false
+
+      body.to_s.lines.each do |raw|
+        line = raw.chomp
+
+        if line.match?(FENCE)
+          out.concat(flush(run))
+          run = nil
+          in_fence = !in_fence
+          out << raw
+          next
+        end
+
+        if in_fence
+          out << raw
+          next
+        end
+
+        run, emitted = classify(line, raw, run)
+        out.concat(emitted)
+      end
+
+      out.concat(flush(run))
+      out.join
+    end
+
+    # Returns [new_run, lines_to_emit].
+    def classify(line, raw, run)
+      case line
+      when IMAGE_LINE
+        # Set apart from the text above, keeping its indentation, so an image
+        # written under a list item stays inside that item.
+        [nil, flush(run) + (run ? ["\n", raw] : [raw])]
+      when BLANK, THEMATIC, HEADING, TABLE, HTML
+        [nil, flush(run) + [raw]]
+      when QUOTE
+        quote(Regexp.last_match(1), line, run)
+      when LIST
+        [{ kind: :list, prefix: Regexp.last_match(1), parts: [part(Regexp.last_match(2), line)] }, flush(run)]
+      when INDENTED_CODE
+        run ? [continue(run, line), []] : [nil, flush(run) + [raw]]
+      else
+        continuation(line, run)
+      end
+    end
+
+    # A bare ">" separates paragraphs inside a quote, so it ends the run rather
+    # than joining the halves together.
+    def quote(text, line, run)
+      return [nil, flush(run) + ["#{line}\n"]] if text.strip.empty?
+      return [continue(run, line, text), []] if run && run[:kind] == :quote
+
+      [{ kind: :quote, prefix: "> ", parts: [part(text, line)] }, flush(run)]
+    end
+
+    def continuation(line, run)
+      return [continue(run, line), []] if run
+
+      [{ kind: :paragraph, prefix: "", parts: [part(line, line)] }, []]
+    end
+
+    def continue(run, line, text = line)
+      run.merge(parts: run[:parts] + [part(text, line)])
+    end
+
+    def part(text, line)
+      hard = line.match?(HARD_BREAK)
+      # A trailing backslash is the break marker itself, not content.
+      { text: text.strip.sub(/\\\z/, "").rstrip, hard: hard }
+    end
+
+    def flush(run)
+      return [] unless run
+
+      joined = +""
+      run[:parts].each_with_index do |piece, index|
+        joined << (run[:parts][index - 1][:hard] ? "<br>" : " ") unless index.zero?
+        joined << piece[:text]
+      end
+
+      ["#{run[:prefix]}#{joined}\n"]
+    end
+  end
+end

data/lib/notion_publish/links.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module NotionPublish
+  # Rewrites links between documents in the same set.
+  #
+  # A relative link is not merely dead in Notion: the API turns
+  # `](data-management-policy.md)` into `](https://data-management-policy.md)`,
+  # an absolute URL to a hostname nobody owns. Rewriting them to the published
+  # Notion URL before sending avoids that entirely; anything still unresolved is
+  # reported rather than shipped.
+  class Links
+    FENCE = /\A\s*(?:`{3,}|~{3,})/
+    # A link, not an image: the negative lookbehind drops ![alt](...).
+    LINK = /(?<!!)\[([^\]]*)\]\(\s*([^)\s]+?)\s*(?:"[^"]*")?\s*\)/
+    ABSOLUTE = %r{\A(?:https?://|mailto:|#)}i
+
+    # What a relative target becomes once Notion has mangled it. Used by the
+    # relink pass to find links on an already-published page.
+    def self.mangled(target) = "https://#{target}"
+
+    attr_reader :unresolved
+
+    def initialize(registry:, base_dir:)
+      @registry = registry
+      @base_dir = base_dir
+      @unresolved = []
+    end
+
+    def rewrite(body)
+      in_fence = false
+
+      body.to_s.lines.map do |line|
+        if line.match?(FENCE)
+          in_fence = !in_fence
+          next line
+        end
+        next line if in_fence
+
+        line.gsub(LINK) do
+          text = Regexp.last_match(1)
+          target = Regexp.last_match(2)
+          replacement = resolve(target)
+          replacement ? "[#{text}](#{replacement})" : Regexp.last_match(0)
+        end
+      end.join
+    end
+
+    private
+
+    def resolve(target)
+      return nil if target.match?(ABSOLUTE)
+
+      path, fragment = target.split("#", 2)
+      return nil if path.to_s.empty?
+
+      url = @registry.url_for(File.expand_path(path, @base_dir))
+      unless url
+        @unresolved << target
+        return nil
+      end
+
+      fragment ? "#{url}##{fragment}" : url
+    end
+  end
+end

data/lib/notion_publish/log.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module NotionPublish
+  # Request logging for -vv and -vvv, written to stderr so it never mixes with
+  # --json on stdout.
+  #
+  # Level 1 is one line per request: method, path, status, and time taken,
+  # plus a line for each retry. Level 2 adds request and response bodies,
+  # shortened. The token is never logged at any level: it travels only in the
+  # Authorization header, and headers are not logged.
+  class Log
+    BODY_LIMIT = 300
+
+    attr_reader :level
+
+    def initialize(io, level)
+      @io = io
+      @level = level
+      # Requests run on several threads; keep each line whole.
+      @lock = Mutex.new
+    end
+
+    def request(method, uri, status, seconds)
+      line("#{method} #{uri.request_uri} -> #{status} (#{(seconds * 1000).round} ms)")
+    end
+
+    def retrying(status, delay, attempt, max)
+      line("  #{status}: retrying in #{delay}s (attempt #{attempt + 1} of #{max})")
+    end
+
+    def body(direction, text)
+      return unless level >= 2
+      return if text.nil? || text.empty?
+
+      line("  #{direction} #{shorten(text)}")
+    end
+
+    def note(message) = line(message)
+
+    private
+
+    def line(message) = @lock.synchronize { @io.puts("notion-publish: #{message}") }
+
+    def shorten(text)
+      flat = text.to_s.gsub(/\s+/, " ")
+      flat.length > BODY_LIMIT ? "#{flat[0, BODY_LIMIT]}... (#{flat.length} chars)" : flat
+    end
+  end
+end