notion_publish 0.1.0

data/lib/notion_publish/adopter.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "reference"
+require_relative "schema"
+require_relative "sharing"
+
+module NotionPublish
+  # Finds the Notion page that a local file already corresponds to.
+  #
+  # Two ways to say it. Naming the page is exact. Searching by title is a guess,
+  # which is why this is a separate command rather than something publishing
+  # does on anyone's behalf.
+  class Adopter
+    Candidate = Data.define(:id, :url, :title, :last_edited_time, :last_edited_by)
+
+    def initialize(client)
+      @client = client
+    end
+
+    # The exact form: the caller named the page.
+    def by_page(input)
+      uuid = Reference.parse(input).uuid
+      page = @client.get("/v1/pages/#{uuid}")
+      candidate(page)
+    rescue ApiError => e
+      raise unless e.not_found?
+
+      raise Error, Sharing.unreachable(id: uuid, title: Reference.parse(input).slug_title,
+                                       connection_name: @client.connection_name)
+    end
+
+    # The guess: every page in the destination whose title matches exactly.
+    def by_title(target, title)
+      pages = target.page? ? children_of(target.id) : rows_of(target, title)
+      pages.select { |page| candidate(page).title.to_s.casecmp?(title.to_s.strip) }
+           .map { |page| candidate(page) }
+    end
+
+    private
+
+    def rows_of(target, title)
+      key = Schema.for(@client, target).title_key
+      body = { "filter" => { "property" => key, "title" => { "equals" => title.to_s } }, "page_size" => 25 }
+      @client.post("/v1/data_sources/#{target.id}/query", body)["results"] || []
+    end
+
+    def children_of(page_id)
+      @client.get_all("/v1/blocks/#{page_id}/children")
+             .select { |b| b["type"] == "child_page" }
+             .map { |b| @client.get("/v1/pages/#{b['id']}") }
+    end
+
+    def candidate(page)
+      Candidate.new(
+        id: page["id"], url: page["url"], title: title_of(page),
+        last_edited_time: page["last_edited_time"],
+        last_edited_by: user_name(page.dig("last_edited_by", "id"))
+      )
+    end
+
+    def title_of(page)
+      prop = (page["properties"] || {}).values.find { |v| v["type"] == "title" }
+      return nil unless prop
+
+      (prop["title"] || []).map { |chunk| chunk["plain_text"] }.join
+    end
+
+    def user_name(id)
+      return nil unless id
+
+      (@names ||= {})[id] ||= @client.get("/v1/users/#{id}")["name"]
+    rescue ApiError
+      nil
+    end
+  end
+end

data/lib/notion_publish/cli.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "client"
+require_relative "commands"
+require_relative "errors"
+require_relative "log"
+require_relative "manifest"
+require_relative "pool"
+require_relative "version"
+
+module NotionPublish
+  # The notion-publish command line: parses options, dispatches to a command,
+  # and turns failures into messages and exit codes.
+  class CLI
+    OK = 0
+    FAILURE = 1
+    USAGE = 2
+    # Stopped and needs a decision, so a dry run in CI can gate a merge on
+    # "this would need a human" without that reading as a crash.
+    BLOCKED = 3
+    # The shell convention for a process stopped by SIGINT.
+    INTERRUPTED = 130
+
+    SUBCOMMANDS = %w[adopt properties relink republish status].freeze
+    # More than Notion's rate limit allows mostly buys retries; past this it
+    # is a mistake.
+    MAX_JOBS = 10
+
+    # Everything a command needs from the invocation. The client is built on
+    # first use, so a usage error never demands a token.
+    class Context
+      attr_reader :options, :stdout, :stderr, :stdin
+
+      def initialize(options:, stdout:, stderr:, stdin:, client: nil)
+        @options = options
+        @stdout = stdout
+        @stderr = stderr
+        @stdin = stdin
+        @client = client
+      end
+
+      # Under -v, say up front which connection and workspace the token
+      # belongs to. That is the first question when a page cannot be found and
+      # more than one token is in use.
+      def client
+        @client ||= Client.new(token: options[:token], log: log).tap { |c| c.me if log }
+      end
+
+      def log
+        # -v lists every file; request logging starts at -vv.
+        Log.new(stderr, options[:verbose] - 1) if options[:verbose].to_i >= 2
+      end
+    end
+
+    def self.run(argv, stdout: $stdout, stderr: $stderr, stdin: $stdin)
+      new(stdout: stdout, stderr: stderr, stdin: stdin).run(argv)
+    end
+
+    def initialize(stdout: $stdout, stderr: $stderr, stdin: $stdin, client: nil)
+      @options = {}
+      @context = Context.new(options: @options, stdout: stdout, stderr: stderr, stdin: stdin, client: client)
+    end
+
+    def run(argv)
+      argv = Array(argv).dup
+      subcommand = SUBCOMMANDS.include?(argv.first) ? argv.shift : nil
+      args = parser.parse(argv)
+
+      return print_help if @options[:help]
+      return usage("--jobs must be between 1 and #{MAX_JOBS}.") unless (1..MAX_JOBS).cover?(@options.fetch(:jobs, 1))
+      return print_version if @options[:version]
+      return Commands::Whoami.new(@context).call if @options[:whoami]
+
+      dispatch(subcommand, args)
+    rescue OptionParser::ParseError => e
+      usage(e.message)
+    rescue ApiError => e
+      # ApiError is an Error, so it has to be rescued first.
+      stderr.puts api_failure(e)
+      FAILURE
+    rescue Error => e
+      stderr.puts e.message
+      FAILURE
+    rescue Interrupt
+      stderr.puts "Interrupted."
+      INTERRUPTED
+    end
+
+    private
+
+    def stdout = @context.stdout
+    def stderr = @context.stderr
+
+    def dispatch(subcommand, args)
+      case subcommand
+      when "properties" then Commands::Properties.new(@context).call
+      when "status" then Commands::Status.new(@context).call(args.first || Dir.pwd)
+      when "relink" then Commands::Relink.new(@context).call(args.first || Dir.pwd)
+      when "republish" then Commands::Republish.new(@context).call(args.first || Dir.pwd)
+      when "adopt"
+        return usage("Give one Markdown file to adopt.") unless args.length == 1
+
+        Commands::Adopt.new(@context).call(args.first)
+      else publish(args)
+      end
+    end
+
+    def publish(files)
+      case files.length
+      when 1 then Commands::Publish.new(@context).call(files.first)
+      when 0 then usage("No Markdown file given.")
+      else usage("Give one Markdown file at a time (got #{files.length}).")
+      end
+    end
+
+    def print_help
+      stdout.puts parser.help
+      OK
+    end
+
+    def print_version
+      stdout.puts "notion-publish #{VERSION}"
+      OK
+    end
+
+    def usage(message)
+      stderr.puts message
+      stderr.puts
+      stderr.puts parser.help
+      USAGE
+    end
+
+    def api_failure(error)
+      return error.message unless error.restricted?
+
+      <<~MSG.strip
+        #{@context.client.connection_name.inspect} is not allowed to do that (#{error.code}).
+
+        Check the connection's capabilities in the Notion developer portal.
+        Publishing needs "Insert content".
+      MSG
+    end
+
+    # One line per option is easier to scan than any attempt to shorten it.
+    # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength, Metrics/BlockLength
+    def parser
+      @parser ||= OptionParser.new do |o|
+        o.banner = <<~BANNER.strip
+          Usage: notion-publish FILE [options]
+                 notion-publish republish [DIR]        update every page notion-publish-manifest.yml tracks
+                 notion-publish properties [options]   show the destination's schema
+                 notion-publish relink [DIR]           fix links to documents published later
+                 notion-publish adopt FILE [options]   record a page this file already corresponds to
+                 notion-publish status [DIR]           what would happen if you published everything
+        BANNER
+        o.separator ""
+        o.separator "Destination (first one given wins):"
+        o.on("-p", "--parent ID_OR_URL_OR_NAME", "Where to publish: an ID, a Notion URL, or a database name") do |v|
+          @options[:parent] = v
+        end
+        o.on("-d", "--database NAME", "Force name lookup (for a database named like an ID)") do |v|
+          @options[:database] = v
+        end
+        o.separator ""
+        o.separator "Options:"
+        o.on("-P", "--property NAME=VALUE", "Set a property; repeat for multi-valued ones") do |v|
+          (@options[:properties] ||= []) << v
+        end
+        o.on("--properties-json JSON", "Set properties from a JSON object") { |v| @options[:properties_json] = v }
+        o.on("--no-upload", "Do not upload local images (they will not render)") { @options[:upload] = false }
+        o.on("--icon ICON", "Page icon: an emoji, an image URL, or a path to an image") { |v| @options[:icon] = v }
+        o.on("--cover COVER", "Page cover: an image URL or a path to an image") { |v| @options[:cover] = v }
+        o.on("--keep-h1", "Keep the leading H1 in the body as well as the title") { @options[:keep_h1] = true }
+        o.on("--link", "Record this page so it can be updated and linked to") { @options[:link] = true }
+        o.on("--no-link", "Do not record or update; always create a new page") { @options[:link] = false }
+        o.on("--manifest PATH", "Manifest to use (default: #{Manifest::FILENAME} at the repo root)") do |v|
+          @options[:manifest] = v
+        end
+        o.on("--local", "status: do not check Notion, use the recorded hashes only") { @options[:local] = true }
+        o.on("--untracked", "status: list files that were never published") { @options[:untracked] = true }
+        o.on("--page URL_OR_ID", "adopt: the page this file already corresponds to") { |v| @options[:page] = v }
+        o.on("-y", "--yes", "adopt: accept a title match without confirming") { @options[:yes] = true }
+        o.on("--force-properties", "Reapply properties even if nothing else changed") do
+          @options[:force_properties] = true
+        end
+        o.on("-f", "--force", "Publish even if the Notion page changed since it was published") do
+          @options[:force] = true
+        end
+        o.on("-t", "--title TITLE", "Page title (default: front matter, first heading, or filename)") do |v|
+          @options[:title] = v
+        end
+        o.on("-n", "--dry-run", "Resolve and validate, write nothing") { @options[:dry_run] = true }
+        o.on("--json", "Emit one JSON object per document on stdout") { @options[:json] = true }
+        o.on("--token TOKEN", "API token (default: $#{Client::TOKEN_ENV_VARS.join(', $')})") do |v|
+          @options[:token] = v
+        end
+        o.on("--whoami", "Show what the token authenticates as") { @options[:whoami] = true }
+        o.on("--no-progress", "Do not show a progress line in a terminal") { @options[:no_progress] = true }
+        o.on("-j", "--jobs N", Integer, "Pages to check at once (default #{Pool::SIZE}; 1 runs one at a time)") do |v|
+          @options[:jobs] = v
+        end
+        o.on("-v", "--verbose", "List every file; -vv logs API requests; -vvv adds bodies") do
+          @options[:verbose] = (@options[:verbose] || 0) + 1
+        end
+        o.on("--version", "Show version") { @options[:version] = true }
+        o.on("-h", "--help", "Show this message") { @options[:help] = true }
+      end
+    end
+  end
+end

data/lib/notion_publish/client.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "net/http"
+require "uri"
+
+require_relative "errors"
+require_relative "log"
+require_relative "version"
+
+module NotionPublish
+  # A small hand-rolled Notion client.
+  #
+  # There is no official Ruby SDK, and every community gem on RubyGems predates
+  # both the data-source split (2025-09-03) and the markdown endpoints, so
+  # wrapping one would mean fighting a client that models an older API. The
+  # surface we need is five endpoints, so this is Net::HTTP and no dependencies.
+  class Client
+    API_ORIGIN = "https://api.notion.com"
+    API_VERSION = "2026-03-11"
+
+    # Env vars are checked in this order. NOTION_API_TOKEN is what Notion's own
+    # `ntn` CLI reads; NOTION_API_KEY is what its quickstart tells people to set.
+    TOKEN_ENV_VARS = %w[NOTION_API_TOKEN NOTION_API_KEY].freeze
+
+    RETRYABLE_STATUSES = [429, 502, 503, 504, 529].freeze
+    MAX_ATTEMPTS = 4
+    PAGE_SIZE = 100
+    USER_AGENT = "notion-publish/#{VERSION} (+https://github.com/outsidecto/notion-publish)".freeze
+
+    attr_reader :api_version
+
+    def self.token_from_env(env = ENV)
+      TOKEN_ENV_VARS.each do |name|
+        value = env[name]
+        return value unless value.nil? || value.strip.empty?
+      end
+      nil
+    end
+
+    # +log+ is a Log, or nil for silence.
+    def initialize(token: nil, api_version: API_VERSION, sleeper: method(:sleep), log: nil)
+      @token = token || self.class.token_from_env
+      raise MissingToken, TOKEN_ENV_VARS if @token.nil? || @token.strip.empty?
+
+      @api_version = api_version
+      @sleeper = sleeper
+      @log = log
+      # Net::HTTP is not safe to share between threads, so each thread that
+      # makes requests gets its own kept-alive connection.
+      @connections = {}
+      @lock = Monitor.new
+    end
+
+    def delete(path) = request(Net::HTTP::Delete, path)
+    def get(path, query = nil)  = request(Net::HTTP::Get, path, query: query)
+    def post(path, body = nil)  = request(Net::HTTP::Post, path, body: body)
+    def patch(path, body = nil) = request(Net::HTTP::Patch, path, body: body)
+
+    # Every result of a paginated GET, following next_cursor to the end.
+    def get_all(path, query = {})
+      results = []
+      cursor = nil
+      loop do
+        page = get(path, query.merge("page_size" => PAGE_SIZE, "start_cursor" => cursor))
+        results.concat(page["results"] || [])
+        cursor = page["next_cursor"]
+        break unless page["has_more"] && cursor
+      end
+      results
+    end
+
+    # Sends file bytes to the upload URL handed back by POST /v1/file_uploads.
+    # That endpoint wants multipart/form-data rather than JSON, so it does not
+    # go through #request.
+    def post_file(url, path:, content_type:)
+      uri = URI(url)
+      boundary = "notion-publish-#{Time.now.to_i}-#{rand(1 << 32)}"
+
+      req = authorized(Net::HTTP::Post.new(uri))
+      req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+      req.body = multipart(boundary, path, content_type)
+
+      started = monotonic
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 120) do |http|
+        http.request(req)
+      end
+      # The body is file bytes, so describe it rather than print it.
+      trace(req, response, monotonic - started, sent: "(#{File.size(path)} bytes of #{content_type})")
+      parsed = parse(response)
+      return parsed if response.code.to_i.between?(200, 299)
+
+      raise ApiError.new(status: response.code.to_i, body: parsed)
+    end
+
+    # Keeps the token out of logs and exception reports.
+    def inspect = "#<#{self.class.name} api_version=#{@api_version}>"
+
+    # Identity of the token itself. Cached: the CLI asks for it when building
+    # error messages, which can happen more than once per run.
+    def me
+      @lock.synchronize { @me ||= fetch_me }
+    end
+
+    # Human name of the connection or person this token authenticates as, for
+    # error messages that have to tell someone what to share a page with.
+    def connection_name
+      me["name"] || "your integration"
+    end
+
+    # What kind of credential this is: :person for a personal access token,
+    # :bot_user for a connection a user owns, or :bot_workspace for an internal
+    # connection owned by the workspace. Only the last cannot act as anyone.
+    def credential_kind
+      case me["type"]
+      when "person" then :person
+      when "bot"
+        me.dig("bot", "owner", "type") == "user" ? :bot_user : :bot_workspace
+      end
+    end
+
+    private
+
+    def fetch_me
+      get("/v1/users/me").tap do |found|
+        @log&.note("authenticated as #{found['name'].inspect} in #{found.dig('bot', 'workspace_name').inspect}")
+      end
+    end
+
+    def multipart(boundary, path, content_type)
+      # Force binary: joining image bytes with UTF-8 strings raises otherwise.
+      [
+        "--#{boundary}\r\n",
+        %(Content-Disposition: form-data; name="file"; filename="#{File.basename(path)}"\r\n),
+        "Content-Type: #{content_type}\r\n\r\n",
+        File.binread(path),
+        "\r\n--#{boundary}--\r\n"
+      ].map { |part| part.dup.force_encoding(Encoding::BINARY) }.join
+    end
+
+    def authorized(req)
+      req["Authorization"] = "Bearer #{@token}"
+      req["Notion-Version"] = @api_version
+      req["User-Agent"] = USER_AGENT
+      req
+    end
+
+    def build(klass, path, body, query)
+      uri = URI.join(API_ORIGIN, path)
+      uri.query = URI.encode_www_form(query.compact) if query && !query.empty?
+
+      req = authorized(klass.new(uri))
+      req["Accept"] = "application/json"
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      req
+    end
+
+    def request(klass, path, body: nil, query: nil, attempt: 1)
+      req = build(klass, path, body, query)
+      started = monotonic
+      response = http.request(req)
+      status = response.code.to_i
+      trace(req, response, monotonic - started)
+
+      if RETRYABLE_STATUSES.include?(status) && attempt < MAX_ATTEMPTS
+        delay = retry_delay(response, attempt)
+        @log&.retrying(status, delay, attempt, MAX_ATTEMPTS)
+        @sleeper.call(delay)
+        return request(klass, path, body: body, query: query, attempt: attempt + 1)
+      end
+
+      parsed = parse(response)
+      return parsed if status.between?(200, 299)
+
+      error_class = status == 429 ? RateLimited : ApiError
+      raise error_class.new(status: status, body: parsed)
+    end
+
+    def trace(req, response, seconds, sent: req.body)
+      return unless @log
+
+      @log.request(req.method, req.uri, response.code, seconds)
+      @log.body(">", sent)
+      @log.body("<", response.body)
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Notion sends Retry-After on 429. Everything else gets exponential backoff.
+    def retry_delay(response, attempt)
+      after = response["Retry-After"].to_f
+      return after if after.positive?
+
+      2**(attempt - 1)
+    end
+
+    def parse(response)
+      body = response.body.to_s
+      return {} if body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "code" => "invalid_response", "message" => body[0, 200] }
+    end
+
+    # One connection per thread, kept open for the run: a publish makes a
+    # dozen calls.
+    def http
+      @lock.synchronize { @connections[Thread.current] ||= connect }
+    end
+
+    def connect
+      uri = URI(API_ORIGIN)
+      connection = Net::HTTP.new(uri.host, uri.port)
+      connection.use_ssl = true
+      connection.open_timeout = 10
+      connection.read_timeout = 60
+      connection.start
+      connection
+    end
+  end
+end

data/lib/notion_publish/commands/adopt.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "../notion_digest"
+require_relative "command"
+require_relative "../adopter"
+require_relative "../document"
+
+module NotionPublish
+  module Commands
+    # Records that a local file and an existing Notion page are the same
+    # document. Changes neither.
+    #
+    # Deliberately does not record source_sha256: adoption asserts identity,
+    # not that the page already holds this content, so the next publish always
+    # runs rather than reporting it unchanged.
+    class Adopt < Command
+      def call(path)
+        document = Document.load(path)
+        map = Manifest.locate(path, override: options[:manifest])
+        source = File.expand_path(path)
+
+        if (existing = map.entry(source))
+          raise Error, already_adopted(path, existing)
+        end
+
+        candidate = choose(document, path)
+        return CLI::FAILURE unless candidate
+
+        record(map, source, candidate)
+        stdout.puts "Adopted #{path}"
+        stdout.puts "  #{candidate.url}"
+        stdout.puts "Run notion-publish to update it."
+        CLI::OK
+      end
+
+      private
+
+      def record(map, source, candidate)
+        markdown = client.get("/v1/pages/#{candidate.id}/markdown")["markdown"].to_s
+        map.workspace_id = client.me.dig("bot", "workspace_id")
+        map.record(source, Manifest::Entry.new(id: candidate.id, url: candidate.url,
+                                               notion_sha256: NotionDigest.of(markdown),
+                                               flag_properties: []))
+      end
+
+      def choose(document, path)
+        adopter = Adopter.new(client)
+        return adopter.by_page(options[:page]) if options[:page]
+
+        target = resolve_destination(document, settings_for(path))
+        title = options[:title] || document.title
+        found = adopter.by_title(target, title)
+
+        case found.length
+        when 1 then confirm(found.first, target, title)
+        when 0 then raise Error, nothing_matches(title, target)
+        else raise Error, too_many(title, target, found)
+        end
+      end
+
+      def confirm(candidate, target, title)
+        return candidate if options[:yes]
+        raise Error, needs_a_terminal(candidate, title) unless stdin.tty?
+
+        stdout.puts "One page in #{target.title.inspect} is titled #{title.inspect}:"
+        stdout.puts "  #{candidate.url}"
+        stdout.puts "  last edited #{candidate.last_edited_time.to_s[0, 10]} by #{candidate.last_edited_by}"
+        stdout.puts
+        stdout.puts "Adopting means the next publish will replace that page's contents."
+        stdout.print "Adopt it? [y/N] "
+        candidate if stdin.gets.to_s.strip.casecmp?("y")
+      end
+
+      def already_adopted(path, entry)
+        <<~MSG.strip
+          #{path} already points at a page:
+            #{entry.url}
+
+          Delete that entry from #{Manifest::FILENAME} first if you meant to point it
+          somewhere else.
+        MSG
+      end
+
+      def nothing_matches(title, target)
+        <<~MSG.strip
+          No page in #{target.title.inspect} is titled #{title.inspect}.
+
+          Nothing to adopt. Publish it instead:
+            notion-publish <file> --parent #{target.title.inspect}
+        MSG
+      end
+
+      def too_many(title, target, found)
+        lines = ["More than one page in #{target.title.inspect} is titled #{title.inspect}:", ""]
+        found.each { |c| lines << "  #{c.url}" }
+        lines << "" << "Choose one with --page <url>."
+        lines.join("\n")
+      end
+
+      def needs_a_terminal(candidate, title)
+        <<~MSG.strip
+          Found one page titled #{title.inspect}:
+            #{candidate.url}
+
+          Adopting replaces that page's contents on the next publish, and there is
+          no terminal here to confirm it. Pass --yes to answer in advance, or
+          --page <url> to name the page outright.
+        MSG
+      end
+    end
+  end
+end