stream_weaver 0.3.0

data/lib/stream_weaver/canvas/doc_store.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'securerandom'
+# Mutually required with doc_roots (which needs DOCS_SUBPATH/DEFAULT_ROOT for
+# its scan and its global group). Safe in both load orders: Ruby marks a file
+# as loaded before evaluating it, so the second require is a no-op, and
+# neither file touches the other's constants at load time -- only inside
+# method bodies.
+require 'stream_weaver/canvas/doc_roots'
+
+module StreamWeaver
+  module Canvas
+    # Tier 2 (persistent, in-repo) storage for canvas docs the user has
+    # explicitly chosen to keep. Sibling of Canvas::History (Tier 1, ephemeral).
+    #
+    # Resolved path priority:
+    #   1. ENV['STREAMWEAVER_DOC_ROOT']            (test/override hook)
+    #   2. <git_root>/docs/streamweaver_canvas     (when invoked inside a repo)
+    #   3. ~/.streamweaver/canvas                  (no-repo fallback)
+    #
+    # Git-root detection walks the filesystem looking for a .git entry on the
+    # current working directory or any ancestor. We deliberately do NOT shell
+    # out to `git`: filesystem walking is faster, has no PATH/install
+    # dependency, and is easy to stub in specs. A .git that is either a
+    # directory (normal repo) or a file (worktree/submodule pointer) counts
+    # as a hit -- File.exist? covers both.
+    #
+    # Doc names are validated against an allowlist (alnum + . _ -, must start
+    # with alnum) and an explicit '..'-substring + null-byte check. Bad names
+    # raise ArgumentError -- raising rather than sanitizing keeps the contract
+    # explicit and avoids silently writing to an unexpected file. The
+    # extension is forced and idempotent: .rb and .org are both valid
+    # (save("foo") and save("foo.rb") both write to <path>/foo.rb; likewise
+    # for .org), defaulting to .rb when neither is present. Extra dots
+    # within the name are allowed (auth-flow.v2 -> auth-flow.v2.rb) since
+    # the allowlist already permits '.' and descriptive multi-segment names
+    # are useful.
+    #
+    # No cleanup method: Tier 2 is permanent. Git is the cleanup mechanism.
+    module DocStore
+      DEFAULT_ROOT  = File.expand_path('~/.streamweaver/canvas')
+      DOCS_SUBPATH  = File.join('docs', 'streamweaver_canvas')
+      VALID_NAME    = /\A[A-Za-z0-9][A-Za-z0-9._-]*\z/
+
+      # Marks a file as a StreamWeaver doc body.
+      #
+      # A saved doc is a bare DSL body -- no require, no app wrapper -- so
+      # nothing about the file announces what it is. Tooling that finds one out
+      # of context (a renderer looking at a GitHub blob, an editor plugin, a
+      # human) has no reliable way to tell it apart from ordinary Ruby.
+      # Guessing from content does not work either: substantial docs use a dozen
+      # distinct DSL calls, but a thin one may be almost entirely `md`.
+      #
+      # A comment costs nothing at eval time and travels with the file wherever
+      # it goes, independent of path or extension.
+      STAMP = '# streamweaver-doc: v1'
+
+      # Recognizes the stamp anywhere in a leading comment block, so it still
+      # matches if a magic comment (frozen_string_literal) or a title comment
+      # sits above it. The version is captured but not pinned -- a v2 doc should
+      # still be recognizable as a doc.
+      STAMP_RE = /^#\s*streamweaver-doc:\s*v(\d+)\s*$/
+
+      # How far into a file to look. Deep enough for a comment header, shallow
+      # enough that a stray match in prose does not count.
+      STAMP_SCAN_LINES = 10
+
+      module_function
+
+      # Resolves the docs directory. Read fresh on every call so an ENV
+      # override flips behavior mid-process (specs rely on this).
+      def path
+        env = ENV['STREAMWEAVER_DOC_ROOT']
+        return env if env && !env.empty?
+
+        if (root = git_root)
+          File.join(root, DOCS_SUBPATH)
+        else
+          DEFAULT_ROOT
+        end
+      end
+
+      # Walks up from `start` looking for a .git entry. Returns the absolute
+      # path of the directory that contains it, or nil at the filesystem
+      # root. Treats .git as a hit whether it is a directory or a file
+      # (worktree/submodule).
+      def git_root(start = Dir.pwd)
+        dir = File.expand_path(start)
+        loop do
+          return dir if File.exist?(File.join(dir, '.git'))
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+
+      # Writes `dsl` to <path>/<normalized_name>.rb and returns the absolute
+      # path. Creates the docs directory if missing. Overwrites any existing
+      # file with the same name (Tier 2 docs are user-managed; collisions
+      # mean the user is intentionally updating).
+      #
+      # scope/source_dir (stream_weaver-j3b3): a caller with an explicit
+      # destination in mind (the Save-as-doc toggle) passes both. `scope:
+      # :global` always writes to DEFAULT_ROOT. `scope: :repo` (the default)
+      # writes under `source_dir` when given; when `source_dir` is nil (no
+      # caller preference, e.g. a caller with no repo context to offer) it
+      # falls back to the existing auto-detected `path` -- unchanged
+      # behavior for every pre-existing caller.
+      #
+      # Only .rb output gets the `# streamweaver-doc: v1` stamp -- .org output
+      # already self-identifies via its own `#+STREAMWEAVER_DSL: 1` header
+      # keyword (org-doc-format-design.md), which must be the file's first
+      # line unconditionally. Prepending the .rb-style stamp in front of it
+      # would violate that and, being a bare `#` line rather than a `#+`
+      # keyword, wouldn't even be recognized by org-ruby.
+      #
+      # The write is atomic: content goes to a temp file in the SAME directory
+      # (so the rename stays on one filesystem, where POSIX guarantees it is
+      # atomic) and is then renamed over the target. A plain File.write
+      # truncates first, so a concurrent reader -- canvas-read's docs scan on
+      # every render, or another process's GET -- can observe an empty or
+      # half-written file. The temp name is dotted and .tmp-suffixed so it
+      # matches neither the *.rb nor the *.org globs even in the instant it
+      # exists, and it is removed if the write or rename fails so a failure
+      # never litters the docs directory.
+      def save(name, dsl, scope: :repo, source_dir: nil)
+        filename = normalize_name(name)
+        dir = target_dir(scope, source_dir)
+        FileUtils.mkdir_p(dir)
+
+        full = File.join(dir, filename)
+        content = filename.end_with?('.org') ? dsl : stamp(dsl)
+        tmp = File.join(dir, ".#{filename}.#{Process.pid}.#{SecureRandom.hex(4)}.tmp")
+        begin
+          File.write(tmp, content)
+          File.rename(tmp, full)
+        rescue StandardError
+          FileUtils.rm_f(tmp)
+          raise
+        end
+
+        # Half of canvas-read's cross-repo discovery (stream_weaver-iugu):
+        # saving into a repo is what makes that repo's docs findable from a
+        # canvas-read launched anywhere else. Deliberately after the rename,
+        # so a failed write never registers a root that has no docs in it.
+        # DocRoots.record swallows its own filesystem errors -- a registry
+        # that can't be written must never fail the save it followed.
+        DocRoots.record(dir)
+
+        full
+      end
+
+      # Prepends `use_theme`/`use_layout` declarations so a saved doc renders
+      # with the theme/layout of the canvas session it came from
+      # (stream_weaver-csf). Saved docs are re-rendered later by canvas-read,
+      # which has no session to inherit from -- only the DSL text -- so the
+      # metadata has to live in the text itself.
+      #
+      # Shared by BOTH save routes (BridgeServer's /canvas/:name/save-doc and
+      # Reader's /save-doc) deliberately: duplicating the prepend logic would
+      # let the two Save-as-doc buttons silently write different files.
+      #
+      # Idempotent: a DSL that already declares either directive keeps its own,
+      # so re-saving never stacks duplicates. nil theme/layout are skipped --
+      # that's the Reader's promote-from-history case, where the snapshot was
+      # written by `canvas-push` (which never sees the bridge session's theme),
+      # so those docs keep rendering with canvas-read's default.
+      def dsl_with_metadata(dsl, theme: nil, layout: nil)
+        lines = []
+        lines << "use_theme :#{theme}"   if theme  && !dsl.match?(/^[ \t]*use_theme\b/)
+        lines << "use_layout :#{layout}" if layout && !dsl.match?(/^[ \t]*use_layout\b/)
+        return dsl if lines.empty?
+
+        (lines + [dsl]).join("\n")
+      end
+
+      # True when `source` already declares itself a StreamWeaver doc.
+      #
+      # Only the first STAMP_SCAN_LINES are considered, so a doc that happens to
+      # quote the stamp inside prose or a code_block further down is not
+      # mistaken for a stamped file.
+      def stamped?(source)
+        return false unless source.is_a?(String)
+
+        source.each_line.first(STAMP_SCAN_LINES).any? { |line| line.match?(STAMP_RE) }
+      end
+
+      # Returns `dsl` with the stamp on its first line, or unchanged if it is
+      # already stamped.
+      #
+      # Idempotent on purpose: saving over an existing doc is the normal way to
+      # update one, and the stamp must not accumulate. Prepending is safe even
+      # when the body opens with `# frozen_string_literal: true` -- Ruby honors
+      # a magic comment anywhere in the leading comment block, not only on line
+      # one.
+      def stamp(dsl)
+        text = dsl.to_s
+        return text if stamped?(text)
+        # Defense in depth, not currently reachable: `save`'s own
+        # filename.end_with?('.org') check is what actually protects org
+        # content today (`stamp` has no other caller). Kept here too so a
+        # future caller of `stamp` directly can't reintroduce the exact bug
+        # c1df5f6 fixed -- the .rb-style stamp corrupting .org's hard
+        # requirement that '#+STREAMWEAVER_DSL: 1' be the literal first line.
+        return text if text.start_with?('#+')
+        return "#{STAMP}\n" if text.empty?
+
+        "#{STAMP}\n#{text}"
+      end
+
+      # Strips a single trailing .rb or .org (case-sensitive), validates the
+      # resulting basename against VALID_NAME with explicit '..' and
+      # null-byte rejection, then re-adds whichever extension was detected
+      # (defaulting to .rb when neither is present). Bare ".rb"/".org"
+      # normalize to an empty basename and are rejected.
+      def normalize_name(name)
+        raise ArgumentError, "invalid doc name: #{name.inspect}" unless name.is_a?(String)
+
+        ext, stripped = if name.end_with?('.rb')
+                          ['.rb', name[0...-3]]
+                        elsif name.end_with?('.org')
+                          ['.org', name[0...-4]]
+                        else
+                          ['.rb', name]
+                        end
+
+        unless !stripped.empty? &&
+               !stripped.include?('..') &&
+               !stripped.include?("\0") &&
+               stripped.match?(VALID_NAME)
+          raise ArgumentError, "invalid doc name: #{name.inspect}"
+        end
+
+        "#{stripped}#{ext}"
+      end
+      private_class_method :normalize_name
+
+      # Resolves the destination directory for `save`'s scope/source_dir
+      # arguments. See `save`'s comment for the semantics.
+      def target_dir(scope, source_dir)
+        return DEFAULT_ROOT if scope == :global
+        return File.join(source_dir, DOCS_SUBPATH) if source_dir
+
+        path
+      end
+      private_class_method :target_dir
+    end
+  end
+end

data/lib/stream_weaver/canvas/gist_publisher.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'timeout'
+require_relative 'doc_store'
+require_relative '../org/writer'
+
+module StreamWeaver
+  module Canvas
+    # Publishes a canvas doc to a secret GitHub gist via the `gh` CLI.
+    #
+    # This is the only place in StreamWeaver that shells out to `gh` and the
+    # only place that writes to an external, user-visible URL -- a coworker
+    # opens the link this returns, so a bug here ships wrong content to a
+    # real person rather than to a file the author can quietly fix.
+    #
+    # Both files go up in ONE api call: the rendered `.org` (what GitHub
+    # renders as a formatted doc -- the reason for sharing at all) and the
+    # re-runnable `.rb` DSL source (the source of truth). One save is
+    # therefore exactly one gist revision, which is what makes
+    # `<gist_url>/revisions` a meaningful timeline instead of a stutter of
+    # half-updates. `gh gist create`/`gh gist edit` were rejected for this:
+    # neither puts two files into a single call cleanly across the
+    # create-vs-update split, and neither gives direct control over the JSON
+    # payload.
+    #
+    # Visibility: secret, always. `public` is never sent -- not on create
+    # (gh's own API default is secret, so omitting the key is the same as
+    # asking for secret, with one less thing to get backwards) and never on
+    # update, where GitHub silently ignores it because gist visibility is
+    # immutable after creation. Sending a key that is either redundant or
+    # ignored is a landmine for whoever reads this next.
+    module GistPublisher
+      # Seconds to wait on one `gh api` round trip. The caller is a Sinatra
+      # request thread serving the canvas's Save-as-doc dialog; without this,
+      # a stalled TLS handshake against api.github.com hangs that thread with
+      # the user staring at a spinner. 20s is generous for a two-file POST and
+      # still short enough to fail visibly.
+      #
+      # Timeout.timeout unblocks the CALLER, not the child: a `gh` that is
+      # truly wedged may outlive the request by a few seconds before its own
+      # network layer gives up. That is acceptable -- it holds no lock and
+      # writes nothing of ours -- and is the reason this is a timeout rather
+      # than a process kill.
+      TIMEOUT_SECONDS = 20
+
+      # `existing_id` reaches us from the gist store and is interpolated into
+      # the API path (`/gists/<id>`), where a `..` segment would silently
+      # retarget the request at a different endpoint. argv is already
+      # shell-safe, so this is not about shell injection -- it is about not
+      # letting a corrupted store entry aim a PATCH somewhere unintended.
+      #
+      # Alphanumeric rather than strictly hex: today's gist ids are hex, but
+      # the id is GitHub's to define and the only property this actually needs
+      # is "contains no path syntax".
+      VALID_GIST_ID = /\A[A-Za-z0-9]+\z/
+
+      # Stderr shapes that mean "your credentials are the problem", as
+      # opposed to any other API failure. gh's own wording here is
+      # famously unhelpful out of context ("Bad credentials (HTTP 401)"
+      # tells a canvas user nothing), so these get rewritten into copy that
+      # names the actual fix.
+      #
+      # Every alternative is a specific known gh/GitHub phrase, never a bare
+      # keyword. That is deliberate: rewriting an unrelated failure into
+      # "run `gh auth login`" would hand the user a confident wrong diagnosis,
+      # which is worse than passing gh's own message through untouched. Two
+      # consequences of that rule worth naming: a bare HTTP 403 is NOT matched
+      # (rate limiting and org policy return it too), and the word "scope"
+      # only counts next to language about it being missing or required.
+      AUTH_FAILURE_RE = /
+        HTTP\s+401
+        | bad\s+credentials
+        | gh\s+auth\s+login
+        | GH_TOKEN
+        | not\s+accessible\s+by\s+personal\s+access\s+token
+        | (?:required|missing|insufficient|granted|needs)[^\n]{0,60}\bscopes?\b
+        | \bscopes?\b[^\n]{0,60}(?:required|missing|insufficient)
+        | SAML
+      /xi
+
+      # A deleted-upstream gist. Only meaningful on an update -- see #publish.
+      NOT_FOUND_RE = /HTTP\s+404|\bnot\s+found\b/i
+
+      AUTH_HELP = 'GitHub CLI could not authenticate. Run `gh auth login` and make sure the ' \
+                  'token has the `gist` scope.'
+
+      module_function
+
+      # Renders `dsl` to both formats and publishes them as one gist.
+      #
+      # Returns a plain hash rather than raising, because every caller is an
+      # HTTP handler that has to turn the outcome into a JSON body either way:
+      #
+      #   success: { ok: true, id:, url:, revisions:, action: "create"|"update",
+      #              coverage: {...} }
+      #   failure: { ok: false, error: "<message fit to show a user>" }
+      #
+      # On the stale-id recovery path the success hash also carries
+      # `forget_stale_id: "<old id>"` -- the caller's cue to drop that id from
+      # GistStore so the next save updates the new gist instead of chasing the
+      # deleted one again.
+      #
+      # ArgumentError from an invalid doc name is deliberately NOT caught: it
+      # is a 422 (the user typed a bad name), not a 502 (the publish failed),
+      # and the existing save-doc handlers already map ArgumentError that way.
+      # Swallowing it here into `ok: false` would flatten that distinction.
+      def publish(name:, dsl:, theme: nil, layout: nil, existing_id: nil)
+        base = base_name(name)
+
+        writer = StreamWeaver::Org::Writer.new(dsl)
+        org_text = writer.call
+        coverage = writer.coverage
+        rb_text = DocStore.dsl_with_metadata(dsl, theme: theme, layout: layout)
+
+        payload = build_payload(base, org_text, rb_text)
+
+        if existing_id
+          unless existing_id.to_s.match?(VALID_GIST_ID)
+            return { ok: false, error: "invalid gist id: #{existing_id.inspect}" }
+          end
+
+          out, err, status = gh_api('PATCH', "/gists/#{existing_id}", payload)
+          return success(out, 'update', coverage) if status.success?
+
+          # A 404 here means the gist was deleted on github.com since we last
+          # recorded it. Publishing is still the thing the user asked for, so
+          # mint a fresh gist rather than failing with a message about an id
+          # they never saw and cannot act on. Only ever done for an update: a
+          # 404 from a create is a real API problem, and retrying it would
+          # just double the failure.
+          return gh_error(err, status) unless err.to_s.match?(NOT_FOUND_RE)
+
+          result = create(payload, coverage)
+          return result unless result[:ok]
+
+          return result.merge(forget_stale_id: existing_id)
+        end
+
+        create(payload, coverage)
+      rescue Timeout::Error
+        { ok: false, error: "gh timed out after #{TIMEOUT_SECONDS}s talking to GitHub" }
+      end
+
+      # Cheap presence check: is the `gh` binary on PATH at all?
+      #
+      # Deliberately NOT an auth check. `gh auth status` costs a network round
+      # trip, and this is called on every canvas render to decide whether the
+      # Gist radio is enabled -- putting a network call there would make the
+      # dialog's responsiveness depend on GitHub being up. Auth problems
+      # surface at publish time instead, where #publish already rewrites them
+      # into actionable copy (see AUTH_HELP).
+      #
+      # Memoized: gh does not appear or vanish mid-process, and the widget
+      # re-renders often enough that respawning a process per render would be
+      # visible.
+      def gh_available?
+        return @gh_available unless @gh_available.nil?
+
+        # system returns nil (not false) when the binary is missing, and the
+        # caller renders this straight into a JSON/HTML attribute -- coerce so
+        # the answer is always a real boolean.
+        @gh_available = system('gh', '--version', out: File::NULL, err: File::NULL) ? true : false
+      end
+
+      def create(payload, coverage)
+        out, err, status = gh_api('POST', '/gists', payload)
+        return gh_error(err, status) unless status.success?
+
+        success(out, 'create', coverage)
+      end
+      private_class_method :create
+
+      # One `gh api` round trip. Array argv, never a shell string: the doc
+      # name and gist id both reach this method from user input, and a shell
+      # string is the one way to turn either into command execution.
+      # `--input -` puts the JSON on stdin so no part of the payload ever
+      # becomes an argument.
+      def gh_api(verb, path, payload)
+        Timeout.timeout(TIMEOUT_SECONDS) do
+          Open3.capture3('gh', 'api', '-X', verb, path, '--input', '-', stdin_data: JSON.generate(payload))
+        end
+      end
+      private_class_method :gh_api
+
+      # Note the absence of a `public` key -- see the module comment. Both the
+      # create and the update send this exact structure, which is what keeps
+      # the two paths from drifting into sending different content.
+      def build_payload(base, org_text, rb_text)
+        {
+          description: description_for(base, org_text),
+          files: {
+            "#{base}.org" => { content: org_text },
+            "#{base}.rb" => { content: rb_text }
+          }
+        }
+      end
+      private_class_method :build_payload
+
+      # The gist description is the line a coworker reads in a list of gists,
+      # so the doc's own title beats the filename when there is one.
+      # Org::Writer emits `#+TITLE:` only when the DSL declares a doc_header.
+      def description_for(base, org_text)
+        title = org_text[/^\#\+TITLE:\s*(.+)$/, 1]&.strip
+        title && !title.empty? ? title : base
+      end
+      private_class_method :description_for
+
+      def success(stdout, action, coverage)
+        body = JSON.parse(stdout.to_s)
+        # A zero-exit gh whose stdout is valid JSON but not a gist object
+        # (`null`, a bare array) would otherwise NoMethodError on body['id']
+        # and reach the Sinatra handler as a 500 stack trace. Nothing in gh
+        # is known to do this -- the guard exists so an unexpected response
+        # degrades to the same readable failure as an unparseable one.
+        return { ok: false, error: "unexpected gh response: #{stdout.to_s[0, 200]}" } unless body.is_a?(Hash)
+
+        {
+          ok: true,
+          id: body['id'],
+          url: body['html_url'],
+          # Every gist is a git repo and `history` is its commit list, so its
+          # length is the revision count the widget shows next to the
+          # /revisions link -- no extra call needed to compute it.
+          revisions: Array(body['history']).length,
+          action: action,
+          coverage: coverage
+        }
+      rescue JSON::ParserError => e
+        { ok: false, error: "could not parse gh response: #{e.message}" }
+      end
+      private_class_method :success
+
+      def gh_error(stderr, status)
+        message = stderr.to_s.strip
+        return { ok: false, error: "#{AUTH_HELP} (gh said: #{message})" } if message.match?(AUTH_FAILURE_RE)
+        return { ok: false, error: "gh exited #{status.exitstatus} with no output" } if message.empty?
+
+        { ok: false, error: message }
+      end
+      private_class_method :gh_error
+
+      # DocStore.normalize_name is the project's single definition of a valid
+      # doc name (allowlist + explicit '..' and null-byte rejection) and it is
+      # what the file-writing save routes already validate against. Reusing it
+      # keeps a name that is legal for a gist identical to one that is legal
+      # for a file, so the two Save-as-doc destinations can never disagree
+      # about what the user typed.
+      #
+      # It is `private_class_method` on DocStore (it has no external caller
+      # today), hence the `send`. Making it public is the better long-term
+      # fix, but doc_store.rb is out of this story's scope -- flagged for
+      # whoever next touches that file.
+      #
+      # normalize_name returns a name WITH its extension; a gist needs the
+      # bare stem, because the publisher appends both extensions itself.
+      def base_name(name)
+        DocStore.send(:normalize_name, name).sub(/\.(rb|org)\z/, '')
+      end
+      private_class_method :base_name
+    end
+  end
+end

data/lib/stream_weaver/canvas/gist_save_handler.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative 'gist_store'
+require_relative 'gist_publisher'
+
+module StreamWeaver
+  module Canvas
+    # scope == 'gist' branch of a save-doc route (share-to-gist epic),
+    # shared between BridgeServer's live-canvas save and Reader's
+    # history-snapshot promotion -- the only difference between the two
+    # callers is whether there's a session's theme/layout to carry
+    # (BridgeServer has one; Reader promotes a snapshot that never saw one,
+    # same accepted limitation as this route's org/rb branches -- see
+    # reader.rb's own comment on dsl_with_metadata).
+    #
+    # `include`d into both Sinatra::Base subclasses rather than left as two
+    # hand-mirrored copies: it started that way (bridge-canvas-gist-endpoint,
+    # then reader-gist-parity), and a second copy is exactly the point past
+    # which "keep it duplicated" stops paying for itself -- `halt` below
+    # resolves to whichever including Sinatra app calls it.
+    module GistSaveHandler
+      # base_name mirrors GistPublisher's own (private) base_name derivation
+      # for a valid name: DocStore.normalize_name never rewrites characters,
+      # it only validates and forces/strips the .rb/.org extension, so
+      # stripping the extension here -- same regex the callers' own org
+      # branches use -- lands on the identical string GistPublisher records
+      # under. A non-String doc_name is passed through as-is (GistStore.lookup
+      # coerces via #to_s, so this can only ever miss, not raise) so
+      # GistPublisher.publish's own DocStore.normalize_name call is what
+      # raises the ArgumentError, exactly like the callers' org/rb branches.
+      def handle_gist_save(dsl, doc_name, theme: nil, layout: nil)
+        rescue_save_errors do
+          base_name = doc_name.is_a?(String) ? doc_name.sub(/\.(rb|org)\z/, '') : doc_name
+          existing_id = GistStore.lookup(base_name)&.dig('id')
+
+          result = GistPublisher.publish(
+            name: doc_name,
+            dsl: dsl,
+            theme: theme,
+            layout: layout,
+            existing_id: existing_id
+          )
+
+          halt 502, { ok: false, error: result[:error] }.to_json unless result[:ok]
+
+          response = {
+            ok: true,
+            gist_url: result[:url],
+            gist_id: result[:id],
+            revisions: result[:revisions],
+            action: result[:action],
+            coverage: result[:coverage]
+          }
+
+          # A GistStore.record failure must never fail an otherwise-successful
+          # publish -- the gist is already live at result[:url] regardless of
+          # whether we can remember it locally. Mirrors how DocStore.save
+          # swallows a DocRoots.record failure (doc_store.rb:151) rather than
+          # raising it back at the caller.
+          begin
+            GistStore.record(
+              base_name, id: result[:id], url: result[:url], revisions: result[:revisions]
+            )
+          rescue StandardError => e
+            response[:warning] = "gist saved, but recording it locally failed: #{e.message}"
+          end
+
+          # Stale-id recovery (see GistPublisher#publish): result[:forget_stale_id],
+          # when present, is the OLD gist id that 404'd on PATCH -- there is
+          # nothing further to clean up for it. GistStore is keyed by doc NAME,
+          # not gist id, and GistStore.record above already overwrote this
+          # doc's one entry with the freshly-minted id, so the stale id was
+          # never left behind under any key to forget.
+          response.to_json
+        end
+      end
+
+      # Shared ArgumentError->422 / StandardError->500 mapping for the
+      # org/rb/gist save-doc branches.
+      def rescue_save_errors
+        yield
+      rescue ArgumentError => e
+        halt 422, { ok: false, error: e.message }.to_json
+      rescue StandardError => e
+        halt 500, { ok: false, error: e.message }.to_json
+      end
+    end
+  end
+end