kward 0.68.0 → 0.69.0

data/templates/default/fulldoc/html/js/kward.js

@@ -0,0 +1,296 @@
+const resetScrollPosition = () => {
+  if (window.location.hash) return
+
+  document.documentElement.scrollTop = 0
+  if (document.body) document.body.scrollTop = 0
+  window.scrollTo(0, 0)
+
+  const main = document.getElementById('main')
+  if (main) {
+    main.scrollTop = 0
+    main.scrollLeft = 0
+  }
+}
+
+if (!window.location.hash && 'scrollRestoration' in history) {
+  history.scrollRestoration = 'manual'
+}
+
+resetScrollPosition()
+window.addEventListener('load', resetScrollPosition)
+window.addEventListener('pageshow', resetScrollPosition)
+window.addEventListener('DOMContentLoaded', resetScrollPosition)
+window.setTimeout(resetScrollPosition, 0)
+window.setTimeout(resetScrollPosition, 50)
+window.setTimeout(resetScrollPosition, 250)
+if (window.requestAnimationFrame) window.requestAnimationFrame(resetScrollPosition)
+
+const guideLinks = {
+  'doc/getting-started.md': 'file.getting-started.html',
+  'doc/usage.md': 'file.usage.html',
+  'doc/configuration.md': 'file.configuration.html',
+  'doc/authentication.md': 'file.authentication.html',
+  'doc/troubleshooting.md': 'file.troubleshooting.html',
+  'doc/memory.md': 'file.memory.html',
+  'doc/personas.md': 'file.personas.html',
+  'doc/extensibility.md': 'file.extensibility.html',
+  'doc/plugins.md': 'file.plugins.html',
+  'doc/web-search.md': 'file.web-search.html',
+  'doc/code-search.md': 'file.code-search.html',
+  'doc/rpc.md': 'file.rpc.html',
+  'doc/releasing.md': 'file.releasing.html'
+}
+
+let pageController = null
+
+const setupGuideSearch = (signal) => {
+  const form = document.querySelector('.kward-guide-search')
+  const input = document.getElementById('kward-guide-search-input')
+  const results = document.getElementById('kward-guide-search-results')
+  const indexNode = document.getElementById('kward-guide-search-index')
+
+  if (!form || !input || !results || !indexNode) return
+
+  let index = []
+  try {
+    index = JSON.parse(indexNode.textContent || '[]')
+  } catch (_error) {
+    return
+  }
+
+  const closeResults = () => {
+    results.classList.remove('open')
+    results.innerHTML = ''
+  }
+
+  const excerpt = (text, query) => {
+    const normalizedText = text.toLowerCase()
+    const normalizedQuery = query.toLowerCase()
+    const matchIndex = normalizedText.indexOf(normalizedQuery)
+    const start = Math.max(0, matchIndex - 70)
+    const end = Math.min(text.length, (matchIndex < 0 ? 0 : matchIndex) + normalizedQuery.length + 120)
+    const prefix = start > 0 ? '…' : ''
+    const suffix = end < text.length ? '…' : ''
+    return `${prefix}${text.slice(start, end).trim()}${suffix}`
+  }
+
+  const search = (query) => {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean)
+    if (terms.length === 0) return []
+
+    return index
+      .map((item) => {
+        const title = item.title || ''
+        const path = item.path || ''
+        const text = item.text || ''
+        const haystack = `${title} ${path} ${text}`.toLowerCase()
+        if (!terms.every((term) => haystack.includes(term))) return null
+
+        const normalizedTitle = title.toLowerCase()
+        const normalizedPath = path.toLowerCase()
+        const titleMatches = terms.filter((term) => normalizedTitle.includes(term)).length
+        const pathMatches = terms.filter((term) => normalizedPath.includes(term)).length
+        return { item, score: titleMatches * 3 + pathMatches * 2 }
+      })
+      .filter(Boolean)
+      .sort((left, right) => right.score - left.score || left.item.title.localeCompare(right.item.title))
+      .slice(0, 6)
+      .map((result) => result.item)
+  }
+
+  const renderResults = () => {
+    const query = input.value.trim()
+    if (query.length < 2) {
+      closeResults()
+      return
+    }
+
+    const matches = search(query)
+    results.innerHTML = ''
+
+    if (matches.length === 0) {
+      const empty = document.createElement('div')
+      empty.className = 'kward-guide-search-empty'
+      empty.textContent = 'No guide results'
+      results.appendChild(empty)
+      results.classList.add('open')
+      return
+    }
+
+    matches.forEach((item) => {
+      const link = document.createElement('a')
+      link.href = item.url
+      link.setAttribute('role', 'option')
+
+      const title = document.createElement('strong')
+      title.textContent = item.title
+      link.appendChild(title)
+
+      const summary = document.createElement('span')
+      summary.textContent = excerpt(item.text || '', query)
+      link.appendChild(summary)
+
+      results.appendChild(link)
+    })
+
+    results.classList.add('open')
+  }
+
+  input.addEventListener('input', renderResults, { signal })
+
+  input.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') {
+      input.value = ''
+      closeResults()
+      input.blur()
+    }
+  }, { signal })
+
+  form.addEventListener('submit', (event) => {
+    event.preventDefault()
+    const firstResult = results.querySelector('a')
+    if (firstResult) visitPage(firstResult.href)
+  }, { signal })
+
+  document.addEventListener('click', (event) => {
+    if (!form.contains(event.target)) closeResults()
+  }, { signal })
+}
+
+const setupNavigation = (signal) => {
+  const toggle = document.querySelector('.kward-nav-toggle')
+
+  if (toggle) {
+    toggle.addEventListener('click', () => {
+      const isOpen = document.body.classList.toggle('kward-nav-open')
+      toggle.setAttribute('aria-expanded', String(isOpen))
+    }, { signal })
+  }
+
+  document.querySelectorAll('.kward-nav-menu-button').forEach((button) => {
+    button.addEventListener('click', (event) => {
+      event.stopPropagation()
+      button.parentElement.classList.toggle('open')
+    }, { signal })
+  })
+
+  document.addEventListener('click', (event) => {
+    document.querySelectorAll('.kward-nav-menu.open').forEach((menu) => {
+      if (!menu.contains(event.target)) menu.classList.remove('open')
+    })
+  }, { signal })
+}
+
+const rewriteGuideLinks = () => {
+  document.querySelectorAll('#filecontents a[href]').forEach((link) => {
+    const target = guideLinks[link.getAttribute('href')]
+    if (target) link.setAttribute('href', target)
+  })
+}
+
+const setupCodeCopy = () => {
+  document.querySelectorAll('pre').forEach((block) => {
+    if (block.closest('.code-copy-wrapper')) return
+
+    const code = block.querySelector('code')
+    if (!code || !navigator.clipboard) return
+
+    const wrapper = document.createElement('div')
+    wrapper.className = 'code-copy-wrapper'
+    block.parentNode.insertBefore(wrapper, block)
+    wrapper.appendChild(block)
+
+    const button = document.createElement('button')
+    button.className = 'copy-code-button'
+    button.type = 'button'
+    button.textContent = 'Copy'
+
+    button.addEventListener('click', async () => {
+      await navigator.clipboard.writeText(code.textContent || '')
+      button.textContent = 'Copied'
+      window.setTimeout(() => {
+        button.textContent = 'Copy'
+      }, 1200)
+    })
+
+    wrapper.appendChild(button)
+  })
+}
+
+const initializePage = () => {
+  if (pageController) pageController.abort()
+  pageController = new AbortController()
+
+  resetScrollPosition()
+  setupGuideSearch(pageController.signal)
+  setupNavigation(pageController.signal)
+  rewriteGuideLinks()
+  setupCodeCopy()
+}
+
+const samePageUrl = (url) => {
+  return url.origin === window.location.origin &&
+    url.pathname === window.location.pathname &&
+    url.search === window.location.search
+}
+
+const navigableUrl = (url) => {
+  if (url.hash) return false
+  if (url.origin !== window.location.origin) return false
+  if (!url.pathname.endsWith('.html') && !url.pathname.endsWith('/')) return false
+  return !samePageUrl(url)
+}
+
+const replacePage = (html, url) => {
+  const nextDocument = new DOMParser().parseFromString(html, 'text/html')
+  const nextBody = nextDocument.body
+  if (!nextBody) throw new Error('Missing response body')
+
+  document.title = nextDocument.title
+  document.body.className = nextBody.className
+  document.body.innerHTML = nextBody.innerHTML
+  window.history.pushState({}, '', url.href)
+  initializePage()
+}
+
+const visitPage = async (href) => {
+  const url = new URL(href, window.location.href)
+
+  if (!navigableUrl(url)) {
+    window.location.href = url.href
+    return
+  }
+
+  document.documentElement.classList.add('kward-page-loading')
+
+  try {
+    const response = await fetch(url.href)
+    if (!response.ok) throw new Error(`Failed to load ${url.href}`)
+
+    const html = await response.text()
+    replacePage(html, url)
+  } catch (_error) {
+    window.location.href = url.href
+  } finally {
+    document.documentElement.classList.remove('kward-page-loading')
+  }
+}
+
+document.addEventListener('click', (event) => {
+  if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+
+  const link = event.target.closest('a[href]')
+  if (!link || link.target || link.hasAttribute('download')) return
+
+  const url = new URL(link.href, window.location.href)
+  if (!navigableUrl(url)) return
+
+  event.preventDefault()
+  visitPage(url.href)
+})
+
+window.addEventListener('popstate', () => {
+  window.location.reload()
+})
+
+document.addEventListener('DOMContentLoaded', initializePage)

data/templates/default/fulldoc/html/setup.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+def generate_assets
+  super
+  asset('css/kward.css', file('css/kward.css', true))
+  asset('js/kward.js', file('js/kward.js', true))
+  asset('images/kward_logo.png', file('images/kward_logo.png', true))
+end

data/templates/default/layout/html/breadcrumb.erb

@@ -0,0 +1,11 @@
+<div id="menu">
+  <% if @contents || @file %>
+    <% if object != '_index.html' %><a href="<%= guide_page? ? url_for(guide_overview) : url_for_index %>">Index</a> &raquo; <% end %>
+    <span class="title"><%= @breadcrumb_title %></span>
+  <% elsif object.is_a?(CodeObjects::Base) %>
+    <a href="<%= url_for_index %>"><% if object.root? || object.type == :method %>Index<% else %>Index (<%= object.name.to_s[0,1] %>)<% end %></a> &raquo;
+    <%= @breadcrumb.map {|obj| "<span class='title'>" + linkify(obj, obj.name) + "</span>" }.join(" &raquo; ") %>
+    <%= @breadcrumb.size > 0 ? " &raquo; " : "" %>
+    <span class="title"><%= object.root? ? "Top Level Namespace" : object.name(true) %></span>
+  <% end %>
+</div>

data/templates/default/layout/html/layout.erb

@@ -0,0 +1,141 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <%= erb(:headers) %>
+  </head>
+  <body class="kward-docs <%= home_page? ? 'kward-home-body' : 'kward-content-body' %>">
+    <div id="main_progress" aria-hidden="true"></div>
+
+    <header class="kward-topbar">
+      <a class="kward-brand" href="<%= url_for('index.html') %>">
+        <img class="kward-brand-logo" src="<%= url_for('images/kward_logo.png') %>" alt="" aria-hidden="true">
+        <span>
+          <strong>Kward</strong>
+        </span>
+      </a>
+      <button class="kward-nav-toggle" type="button" aria-expanded="false" aria-controls="kward-primary-nav" onclick="document.body.classList.toggle('kward-nav-open'); this.setAttribute('aria-expanded', document.body.classList.contains('kward-nav-open'))">
+        Menu
+      </button>
+      <nav id="kward-primary-nav" class="kward-topnav" aria-label="Primary navigation">
+        <a href="<%= url_for('index.html') %>" class="<%= 'active' if home_page? %>">Home</a>
+        <div class="kward-nav-menu <%= 'active' if guide_page? %>">
+          <a class="kward-nav-menu-link" href="<%= url_for('file.README.html') %>">User Guides</a>
+          <button class="kward-nav-menu-button" type="button" aria-label="Open user guides menu">⌄</button>
+          <div class="kward-nav-dropdown">
+            <% guide_groups.each do |title, items| %>
+              <section>
+                <h2><%= h title %></h2>
+                <% items.each do |label, link| %>
+                  <a href="<%= url_for(link) %>"><%= h label %></a>
+                <% end %>
+              </section>
+            <% end %>
+          </div>
+        </div>
+        <a href="<%= url_for('Kward.html') %>" class="<%= 'active' if api_page? %>">API Docs</a>
+      </nav>
+      <form class="kward-guide-search" role="search">
+        <label class="kward-sr-only" for="kward-guide-search-input">Search user guides</label>
+        <input id="kward-guide-search-input" type="search" placeholder="Search guides" autocomplete="off" aria-label="Search user guides" aria-controls="kward-guide-search-results">
+        <div id="kward-guide-search-results" class="kward-guide-search-results" role="listbox" aria-label="Search results"></div>
+      </form>
+      <script type="application/json" id="kward-guide-search-index"><%= guide_search_index_json %></script>
+    </header>
+
+    <% if home_page? %>
+      <main id="main" class="kward-home">
+        <section class="kward-hero">
+          <div class="kward-hero-copy">
+            <p class="kward-eyebrow">⌘ Ruby CLI Coding Agent</p>
+            <h1>Your terminal.<br><span>Your agent.</span></h1>
+            <p class="kward-lede">Kward is an extendable Ruby CLI coding agent that helps you understand your project, edit files, run commands, search the web, and automate workflows—right from your terminal.</p>
+            <div class="kward-actions">
+              <a class="kward-primary-button" href="<%= url_for('file.README.html') %>">Get Started ›</a>
+              <a class="kward-secondary-button" href="https://github.com/kaiwood/kward" target="_blank" rel="noopener noreferrer">View on GitHub</a>
+            </div>
+            <p class="kward-supports">Supports <span>OpenAI</span>, <span>Anthropic</span>, <span>OpenRouter</span> &amp; more.</p>
+          </div>
+          <div class="kward-hero-art" aria-hidden="true">
+            <img src="<%= url_for('images/kward_logo.png') %>" alt="">
+          </div>
+        </section>
+
+        <section id="features" class="kward-feature-strip" aria-label="Feature summary">
+          <article><strong>☏</strong><h2>Chat in your terminal</h2><p>Multi-turn coding conversations.</p></article>
+          <article><strong>▤</strong><h2>Read, write, edit files</h2><p>With read-before-write guardrails.</p></article>
+          <article><strong>›_</strong><h2>Run shell commands</h2><p>Execute local commands safely.</p></article>
+          <article><strong>◎</strong><h2>Search the web</h2><p>Get live answers and inspect repos.</p></article>
+          <article><strong>✣</strong><h2>Extend with plugins</h2><p>Trusted Ruby plugins for workflows.</p></article>
+          <article><strong>▰</strong><h2>Sessions &amp; memory</h2><p>Save, resume, clone, compact, export.</p></article>
+        </section>
+
+        <section class="kward-install-card">
+          <div class="kward-install-copy">
+            <h2>⇩ Install</h2>
+            <p>Install Kward from RubyGems and get started in seconds.</p>
+            <pre><code>gem install kward</code></pre>
+            <p>Then initialize the starter pack, if you want the defaults.</p>
+            <pre><code>kward init</code></pre>
+            <a href="<%= url_for('file.getting-started.html') %>">View full installation docs →</a>
+          </div>
+          <div class="kward-terminal-card">
+            <div class="kward-tabs"><span>Quick Start</span><span>Run from Source</span></div>
+            <pre><code># Start an interactive chat
+kward
+
+# Show available commands and examples
+kward help
+
+# Sign in or save provider credentials
+kward login
+
+# Run one prompt and exit
+kward "Explain this project"
+
+# Use a specific working directory
+kward --working-directory ~/code/project "Explain this project"</code></pre>
+          </div>
+        </section>
+
+        <section class="kward-capabilities">
+          <h2>⌘ What Kward can do</h2>
+          <ul>
+            <li>Keep a multi-turn coding conversation in your terminal.</li>
+            <li>Read, write, and edit workspace files with read-before-write guardrails.</li>
+            <li>Run local shell commands from the workspace.</li>
+            <li>Search the live web and inspect cached public GitHub repositories.</li>
+            <li>Save, resume, clone, compact, and export sessions.</li>
+            <li>Use optional memory, personas, prompt templates, and skills.</li>
+            <li>Extend the Agent with trusted Ruby plugins for custom workflows.</li>
+            <li>Serve an experimental JSON-RPC backend for UI clients.</li>
+          </ul>
+        </section>
+
+        <section class="kward-cta">
+          <div>
+            <strong>▻</strong>
+            <h2>Built for developers. Powered by you.</h2>
+            <p>Open source, extensible, and ready for your workflows.</p>
+          </div>
+          <a class="kward-primary-button" href="https://github.com/kaiwood/kward" target="_blank" rel="noopener noreferrer">View on GitHub</a>
+        </section>
+
+        <%= erb(:footer) %>
+      </main>
+    <% else %>
+      <div class="kward-page">
+        <main id="main" class="kward-content-page <%= guide_page? ? 'kward-guide-page' : 'kward-api-page' %>">
+          <div id="header">
+            <%= erb(:breadcrumb) %>
+            <%= erb(:search) %>
+            <div class="clear"></div>
+          </div>
+
+          <div id="content"><%= yieldall %></div>
+
+          <%= erb(:footer) %>
+        </main>
+      </div>
+    <% end %>
+  </body>
+</html>

data/templates/default/layout/html/setup.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "json"
+
+module KwardDocsNavigation
+  GUIDE_GROUPS = [
+    [
+      "Start here",
+      [
+        ["Getting started", "file.getting-started.html"],
+        ["Usage", "file.usage.html"],
+        ["Configuration", "file.configuration.html"],
+        ["Authentication", "file.authentication.html"],
+        ["Troubleshooting", "file.troubleshooting.html"]
+      ]
+    ],
+    [
+      "Feature guides",
+      [
+        ["Memory", "file.memory.html"],
+        ["Personas", "file.personas.html"],
+        ["Extensibility", "file.extensibility.html"],
+        ["Plugins", "file.plugins.html"],
+        ["Web search", "file.web-search.html"],
+        ["Code search", "file.code-search.html"]
+      ]
+    ],
+    [
+      "Advanced/reference",
+      [
+        ["RPC protocol", "file.rpc.html"],
+        ["Releasing", "file.releasing.html"]
+      ]
+    ]
+  ].freeze
+
+  GUIDE_OVERVIEW = "file.README.html"
+  GUIDE_LINKS = ([GUIDE_OVERVIEW] + GUIDE_GROUPS.flat_map { |_title, items| items.map(&:last) }).freeze
+  GUIDE_SEARCH_FILES = [
+    ["Overview", "README.md", GUIDE_OVERVIEW],
+    *GUIDE_GROUPS.flat_map do |_title, items|
+      items.map do |label, link|
+        source = "doc/#{link.delete_prefix("file.").delete_suffix(".html")}.md"
+        [label, source, link]
+      end
+    end
+  ].freeze
+  GUIDE_FILE_LINKS = {
+    "doc/getting-started.md" => "file.getting-started.html",
+    "doc/usage.md" => "file.usage.html",
+    "doc/configuration.md" => "file.configuration.html",
+    "doc/authentication.md" => "file.authentication.html",
+    "doc/troubleshooting.md" => "file.troubleshooting.html",
+    "doc/memory.md" => "file.memory.html",
+    "doc/personas.md" => "file.personas.html",
+    "doc/extensibility.md" => "file.extensibility.html",
+    "doc/plugins.md" => "file.plugins.html",
+    "doc/web-search.md" => "file.web-search.html",
+    "doc/code-search.md" => "file.code-search.html",
+    "doc/rpc.md" => "file.rpc.html",
+    "doc/releasing.md" => "file.releasing.html"
+  }.freeze
+
+  def guide_groups
+    GUIDE_GROUPS
+  end
+
+  def guide_overview
+    GUIDE_OVERVIEW
+  end
+
+  def guide_search_index_json
+    JSON.generate(guide_search_index).gsub("</", "<\\/")
+  end
+
+  def guide_search_index
+    GUIDE_SEARCH_FILES.filter_map do |title, source, link|
+      next unless File.file?(source)
+
+      content = File.read(source)
+      {
+        title: title,
+        path: source,
+        url: url_for(link),
+        text: content.gsub(/[`*_#>\[\]()]/, " ").gsub(/\s+/, " ").strip
+      }
+    end
+  end
+
+  def current_docs_path
+    serializer = options.serializer
+    return "index.html" unless serializer
+
+    File.basename(serializer.serialized_path(object))
+  end
+
+  def readme_file?
+    defined?(@file) && @file&.name == "README"
+  end
+
+  def guide_file?
+    defined?(@file) && GUIDE_FILE_LINKS.key?(@file&.filename.to_s)
+  end
+
+  def home_page?
+    options.index && readme_file?
+  end
+
+  def guide_page?
+    (readme_file? && !options.index) || guide_file? || GUIDE_LINKS.include?(current_docs_path)
+  end
+
+  def api_page?
+    !home_page? && !guide_page?
+  end
+
+  def diskfile
+    @file.attributes[:markup] ||= markup_for_file('', @file.filename)
+    data = rewrite_guide_links(htmlify(@file.contents, @file.attributes[:markup]))
+    "<div id='filecontents'>" + data + "</div>"
+  end
+
+  def rewrite_guide_links(html)
+    GUIDE_FILE_LINKS.each do |source, target|
+      html = html.gsub(%(href="#{source}"), %(href="#{target}"))
+    end
+    html
+  end
+end
+
+include KwardDocsNavigation
+
+def javascripts
+  super + %w(js/kward.js)
+end
+
+def stylesheets
+  super + %w(css/kward.css)
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kward
 version: !ruby/object:Gem::Version
-  version: 0.68.0
+  version: 0.69.0
 platform: ruby
 authors:
 - Kai Wood
@@ -116,6 +116,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/pages.yml"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile
@@ -129,6 +130,7 @@ files:
 - doc/extensibility.md
 - doc/getting-started.md
 - doc/memory.md
+- doc/personas.md
 - doc/plugins.md
 - doc/releasing.md
 - doc/rpc.md
@@ -161,6 +163,7 @@ files:
 - lib/kward/cli/settings.rb
 - lib/kward/cli/slash_commands.rb
 - lib/kward/cli/stats.rb
+- lib/kward/cli/sysprompt.rb
 - lib/kward/cli/tool_summaries.rb
 - lib/kward/cli_transcript_formatter.rb
 - lib/kward/clipboard.rb
@@ -239,6 +242,8 @@ files:
 - lib/kward/tools/base.rb
 - lib/kward/tools/code_search.rb
 - lib/kward/tools/edit_file.rb
+- lib/kward/tools/fetch_content.rb
+- lib/kward/tools/fetch_raw.rb
 - lib/kward/tools/list_directory.rb
 - lib/kward/tools/read_file.rb
 - lib/kward/tools/read_skill.rb
@@ -246,6 +251,7 @@ files:
 - lib/kward/tools/run_shell_command.rb
 - lib/kward/tools/search/code.rb
 - lib/kward/tools/search/web.rb
+- lib/kward/tools/search/web_fetch.rb
 - lib/kward/tools/tool_call.rb
 - lib/kward/tools/web_search.rb
 - lib/kward/tools/write_file.rb
@@ -253,6 +259,13 @@ files:
 - lib/kward/version.rb
 - lib/kward/workspace.rb
 - lib/main.rb
+- templates/default/fulldoc/html/css/kward.css
+- templates/default/fulldoc/html/images/kward_logo.png
+- templates/default/fulldoc/html/js/kward.js
+- templates/default/fulldoc/html/setup.rb
+- templates/default/layout/html/breadcrumb.erb
+- templates/default/layout/html/layout.erb
+- templates/default/layout/html/setup.rb
 homepage: https://github.com/kaiwood/kward
 licenses:
 - MIT