From 3d7907fd8c2d86dcc1c37722919473f38b33e7f4 Mon Sep 17 00:00:00 2001
From: Jonathan Yang <14588641+Joilence@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:47:09 +0200
Subject: [PATCH] fix(search): move result date from snippet to published

With a session token, kagi search now parses the result date into published (YYYY-MM-DDT00:00:00Z) and removes it from the snippet. Snippets also drop the "Summarize" link text and collapse whitespace. Relative dates such as "Yesterday" stay in the snippet.

Breaking: search and batch CSV output gain a fourth column, so the header is now title,url,snippet,published. pretty and markdown print the date, and --template accepts {{published}}.
---
 CHANGELOG.md                                  |   4 +
 docs/content/docs/commands/search.mdx         |   8 +-
 .../docs/reference/output-contract.mdx        |   5 +
 src/main.rs                                   |  86 ++++++++++-
 src/parser.rs                                 | 134 +++++++++++++++---
 5 files changed, 207 insertions(+), 30 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 903e5ab..bc47568 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,12 +4,16 @@
 
 - `kagi assistant` and `kagi ask-page` JSON output no longer has `meta.version`, `meta.trace`, `message.reply_html`, or `message.trace_id`, because Kagi's v2 Assistant API returns markdown only. `message.id` is now the assistant turn id.
 - `kagi assistant --assistant <built-in> --model <model>` is now an error, because built-in assistants always use their own model.
+- `kagi search --format csv` and `kagi batch --format csv` gain a fourth column: the header is now `title,url,snippet,published`.
 
 ### Fixed
 
 - `kagi assistant` and `kagi ask-page` work again after Kagi moved Assistant to its v2 API; prompts no longer fail with `HTTP 405 Method Not Allowed`.
 - `kagi assistant --assistant` with a built-in assistant such as `Code` now selects it as a model, as the web app does.
 - Assistant citation markers are rewritten to `[^1]`, `[^2]`, ... to match `references_markdown`.
+- `kagi search` snippets no longer include Kagi's "Summarize" link text, and whitespace in snippets is collapsed.
+- `kagi search` with a session token fills `published` with the result's date as `YYYY-MM-DDT00:00:00Z` and removes the date from the snippet. Relative dates such as "Yesterday" stay in the snippet and leave `published` as `null`.
+- `pretty` and `markdown` output print `published` under the URL, `csv` adds the column, and `--template` accepts `{{published}}`, for API-key searches too.
 
 ## [0.20.1]
 
diff --git a/docs/content/docs/commands/search.mdx b/docs/content/docs/commands/search.mdx
index 65691fb..b9cb78e 100644
--- a/docs/content/docs/commands/search.mdx
+++ b/docs/content/docs/commands/search.mdx
@@ -78,7 +78,7 @@ Possible values:
 - `compact` - minified JSON
 - `pretty` - terminal-friendly output
 - `markdown` - markdown list output
-- `csv` - CSV table output
+- `csv` - CSV table output with `title,url,snippet,published` columns
 
 ### `--no-color`
 
@@ -179,7 +179,7 @@ kagi search --no-personalized "rust web framework"
 
 ### `--template <TEMPLATE>`
 
-Render each result with a lightweight template instead of a built-in format. Supported placeholders are `{{rank}}`, `{{title}}`, `{{url}}`, and `{{snippet}}`.
+Render each result with a lightweight template instead of a built-in format. Supported placeholders are `{{rank}}`, `{{title}}`, `{{url}}`, `{{snippet}}`, and `{{published}}` (empty when the result has no date).
 
 ```bash
 kagi search "rust crates" --template '{{rank}}. {{title}} - {{url}}'
@@ -243,12 +243,14 @@ The search response shape is unchanged:
       "title": "Rust Programming Language",
       "url": "https://www.rust-lang.org",
       "snippet": "A language empowering everyone to build reliable and efficient software.",
-      "published": null
+      "published": "2026-10-04T00:00:00Z"
     }
   ]
 }
 ```
 
+With a session token, `published` is the day shown on the result page (`YYYY-MM-DDT00:00:00Z`), or `null` when the page shows no date or a relative one such as "Yesterday", which stays in `snippet`. With `KAGI_API_KEY`, it is the timestamp Kagi's Search API returns.
+
 With `--news`, the response shape is different -- clusters of news articles:
 
 ```json
diff --git a/docs/content/docs/reference/output-contract.mdx b/docs/content/docs/reference/output-contract.mdx
index b0d6c32..e5b8bb1 100644
--- a/docs/content/docs/reference/output-contract.mdx
+++ b/docs/content/docs/reference/output-contract.mdx
@@ -33,6 +33,8 @@ This page documents the current CLI output behavior as implemented in the repo.
 }
 ```
 
+With a session token, `published` is the day shown on the result page (`YYYY-MM-DDT00:00:00Z`), or `null` when the page shows no date or a relative one such as "Yesterday", which stays in `snippet`. With `KAGI_API_KEY`, it is the timestamp Kagi's Search API returns.
+
 ### `kagi search --news`
 
 The News tab vertical returns a different shape -- clusters of articles:
@@ -448,10 +450,13 @@ Kagi's v2 Assistant API returns markdown only, so `kagi assistant` and `kagi ask
 ```text
 1. Result Title
    https://example.com
+   2026-03-16
 
    Description...
 ```
 
+The date line appears when the result has a `published` value.
+
 If the result set is empty, the CLI prints:
 
 ```text
diff --git a/src/main.rs b/src/main.rs
index 1f0b626..1c7bf18 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -2304,6 +2304,7 @@ fn format_template_response(response: &SearchResponse, template: &str) -> String
                 .replace("{{title}}", &result.title)
                 .replace("{{url}}", &result.url)
                 .replace("{{snippet}}", &result.snippet)
+                .replace("{{published}}", result.published.as_deref().unwrap_or(""))
         })
         .collect::<Vec<_>>()
         .join("\n")
@@ -2377,6 +2378,9 @@ fn format_pretty_response(response: &SearchResponse, use_color: bool) -> String
                 result.url,
                 reset_color
             );
+            if let Some(date) = published_date(result.published.as_deref()) {
+                section.push_str(&format!("\n   {date}"));
+            }
             if !result.snippet.trim().is_empty() {
                 section.push_str(&format!("\n\n   {}", result.snippet.trim()));
             }
@@ -2401,6 +2405,9 @@ fn format_markdown_response(response: &SearchResponse) -> String {
         .enumerate()
         .map(|(index, result)| {
             let mut section = format!("## {}. [{}]({})\n\n", index + 1, result.title, result.url);
+            if let Some(date) = published_date(result.published.as_deref()) {
+                section.push_str(&format!("*{date}*\n\n"));
+            }
             if !result.snippet.trim().is_empty() {
                 section.push_str(&format!("{}\n\n", result.snippet.trim()));
             }
@@ -2475,21 +2482,34 @@ fn escape_csv_field(field: &str) -> String {
 
 fn format_csv_response(response: &SearchResponse) -> String {
     if response.data.is_empty() {
-        return "title,url,snippet".to_string();
+        return "title,url,snippet,published".to_string();
     }
 
-    let mut output = String::from("title,url,snippet\n");
+    let mut output = String::from("title,url,snippet,published\n");
 
     for result in &response.data {
         let title = escape_csv_field(&result.title);
         let url = escape_csv_field(&result.url);
         let snippet = escape_csv_field(&result.snippet);
-        output.push_str(&format!("{title},{url},{snippet}\n"));
+        let published = escape_csv_field(result.published.as_deref().unwrap_or(""));
+        output.push_str(&format!("{title},{url},{snippet},{published}\n"));
     }
 
     output
 }
 
+/// Returns `published` for display, shortening an ISO timestamp to its date (`2026-10-04`).
+fn published_date(published: Option<&str>) -> Option<&str> {
+    let published = published?.trim();
+    if published.is_empty() {
+        return None;
+    }
+    match published.get(..10) {
+        Some(date) if date.as_bytes()[4] == b'-' && date.as_bytes()[7] == b'-' => Some(date),
+        _ => Some(published),
+    }
+}
+
 fn build_news_search_request(args: &SearchArgs) -> search::NewsSearchRequest {
     let freshness = args.time.as_ref().and_then(|time| match time {
         SearchTime::Day => Some(search::NewsFreshness::Day),
@@ -5877,8 +5897,8 @@ mod tests {
         RateLimiter, SearchRequestOptions, bool_flag_choice, build_search_request,
         format_assistant_markdown, format_assistant_pretty, format_batch_failure_message,
         format_csv_response, format_markdown_response, format_pretty_response,
-        is_bare_auth_invocation_from, parse_context_memory_json, print_assistant_response,
-        should_fallback_to_session,
+        format_template_response, is_bare_auth_invocation_from, parse_context_memory_json,
+        print_assistant_response, should_fallback_to_session,
     };
     use crate::cli::{AssistantOutputFormat, SearchOrder, SearchTime};
     use crate::error::KagiError;
@@ -5959,6 +5979,58 @@ mod tests {
         assert_eq!(output, "No results found.");
     }
 
+    #[test]
+    fn shows_published_date_in_every_output_format() {
+        let result = |title: &str, published: Option<&str>| SearchResult {
+            t: 0,
+            rank: None,
+            title: title.to_string(),
+            url: format!("https://{}.example", title.to_lowercase()),
+            snippet: format!("{title} snippet"),
+            published: published.map(str::to_string),
+        };
+        let response = SearchResponse {
+            data: vec![
+                result("Dated", Some("2026-10-04T00:00:00Z")),
+                result("Undated", None),
+            ],
+            related_searches: Vec::new(),
+        };
+
+        let pretty = format_pretty_response(&response, false);
+        assert!(
+            pretty.contains("https://dated.example\n   2026-10-04\n\n   Dated snippet"),
+            "{pretty}"
+        );
+        assert!(
+            pretty.contains("https://undated.example\n\n   Undated snippet"),
+            "{pretty}"
+        );
+
+        let markdown = format_markdown_response(&response);
+        assert!(
+            markdown.contains("(https://dated.example)\n\n*2026-10-04*\n\nDated snippet"),
+            "{markdown}"
+        );
+        assert!(
+            markdown.contains("(https://undated.example)\n\nUndated snippet"),
+            "{markdown}"
+        );
+
+        let csv = format_csv_response(&response);
+        assert_eq!(
+            csv,
+            concat!(
+                "title,url,snippet,published\n",
+                "Dated,https://dated.example,Dated snippet,2026-10-04T00:00:00Z\n",
+                "Undated,https://undated.example,Undated snippet,\n"
+            )
+        );
+
+        let template = format_template_response(&response, "{{title}}|{{published}}");
+        assert_eq!(template, "Dated|2026-10-04T00:00:00Z\nUndated|");
+    }
+
     #[test]
     fn omits_blank_snippets_in_pretty_output() {
         let response = SearchResponse {
@@ -6221,7 +6293,7 @@ mod tests {
 
         assert_eq!(
             output,
-            "title,url,snippet\nRust Programming Language,https://www.rust-lang.org,A language empowering everyone to build reliable and efficient software.\n"
+            "title,url,snippet,published\nRust Programming Language,https://www.rust-lang.org,A language empowering everyone to build reliable and efficient software.,\n"
         );
     }
 
@@ -6243,7 +6315,7 @@ mod tests {
 
         assert_eq!(
             output,
-            "title,url,snippet\n\"Rust, \"\"The Language\"\"\",\"https://example.com/a,b\",\"line 1\nline 2\"\n"
+            "title,url,snippet,published\n\"Rust, \"\"The Language\"\"\",\"https://example.com/a,b\",\"line 1\nline 2\",\n"
         );
     }
 
diff --git a/src/parser.rs b/src/parser.rs
index 2ec1119..6fda96d 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -35,19 +35,31 @@ pub fn parse_search_results(html: &str) -> Result<Vec<SearchResult>, KagiError>
     let title_link_selector = selector(".__sri_title_link")?;
     let grouped_title_link_selector = selector(".__srgi-title a")?;
     let snippet_selector = selector(".__sri-desc")?;
+    let time_selector = selector(".__sri-time")?;
+    let summarize_link_selector = selector(".summarize-link")?;
 
     let mut results = Vec::new();
 
     for element in document.select(&search_result_selector) {
-        if let Some(result) = extract_result(&element, &title_link_selector, &snippet_selector) {
+        if let Some(result) = extract_result(
+            &element,
+            &title_link_selector,
+            &snippet_selector,
+            &time_selector,
+            &summarize_link_selector,
+        ) {
             results.push(result);
         }
     }
 
     for element in document.select(&grouped_result_selector) {
-        if let Some(result) =
-            extract_result(&element, &grouped_title_link_selector, &snippet_selector)
-        {
+        if let Some(result) = extract_result(
+            &element,
+            &grouped_title_link_selector,
+            &snippet_selector,
+            &time_selector,
+            &summarize_link_selector,
+        ) {
             results.push(result);
         }
     }
@@ -543,14 +555,34 @@ fn extract_result(
     element: &scraper::element_ref::ElementRef<'_>,
     title_selector: &Selector,
     snippet_selector: &Selector,
+    time_selector: &Selector,
+    summarize_link_selector: &Selector,
 ) -> Option<SearchResult> {
     let title_link = element.select(title_selector).next()?;
     let title = title_link.text().collect::<String>().trim().to_string();
     let url = title_link.value().attr("href")?.trim().to_string();
-    let snippet = element
-        .select(snippet_selector)
-        .next()
-        .map(|node| node.text().collect::<String>().trim().to_string())
+    let desc = element.select(snippet_selector).next();
+    let time = desc.and_then(|node| node.select(time_selector).next());
+    let published = time.and_then(|node| parse_result_date(&node.text().collect::<String>()));
+    let snippet = desc
+        .map(|node| {
+            let mut skipped = node
+                .select(summarize_link_selector)
+                .map(|link| link.id())
+                .collect::<Vec<_>>();
+            // A relative date such as "Yesterday" stays in the snippet.
+            skipped.extend(time.filter(|_| published.is_some()).map(|time| time.id()));
+            let text = node
+                .descendants()
+                .filter(|child| {
+                    !child
+                        .ancestors()
+                        .any(|parent| skipped.contains(&parent.id()))
+                })
+                .filter_map(|child| child.value().as_text().map(|text| &**text))
+                .collect::<String>();
+            collapse_whitespace(&text)
+        })
         .unwrap_or_default();
 
     if title.is_empty() || url.is_empty() {
@@ -563,10 +595,28 @@ fn extract_result(
         title,
         url,
         snippet,
-        published: None,
+        published,
     })
 }
 
+fn collapse_whitespace(text: &str) -> String {
+    text.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+/// Converts a result date such as `Oct 4, 2026` to `2026-10-04T00:00:00Z`; relative dates such
+/// as `Yesterday` return `None`.
+fn parse_result_date(text: &str) -> Option<String> {
+    const MONTHS: [&str; 12] = [
+        "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+    ];
+    let mut parts = text.split_whitespace();
+    let month_name = parts.next()?;
+    let month = MONTHS.iter().position(|name| *name == month_name)? + 1;
+    let day = parts.next()?.strip_suffix(',')?.parse::<u32>().ok()?;
+    let year = parts.next()?.parse::<u32>().ok()?;
+    Some(format!("{year:04}-{month:02}-{day:02}T00:00:00Z"))
+}
+
 fn selector(value: &str) -> Result<Selector, KagiError> {
     Selector::parse(value)
         .map_err(|error| KagiError::Parse(format!("failed to parse selector `{value}`: {error:?}")))
@@ -656,14 +706,26 @@ mod tests {
         <html><body>
           <div class="search-result">
             <a class="__sri_title_link" href="https://example.com/one">One Result</a>
-            <div class="__sri-desc">First snippet</div>
+            <div class="_0_DESC __sri-desc"> <div> <span class="__sri-time">    Oct 4, 2026   </span>
+              First   snippet.   <a class="_0_summarize_page summarize-link" href="/summarizer?url=one">Summarize</a> </div> </div>
+          </div>
+          <div class="search-result">
+            <a class="__sri_title_link" href="https://example.com/undated">Undated Result</a>
+            <div class="__sri-desc">No date here.</div>
+          </div>
+          <div class="search-result">
+            <a class="__sri_title_link" href="https://example.com/relative">Relative Result</a>
+            <div class="__sri-desc"><div><span class="__sri-time"> Yesterday </span> Recent.</div></div>
           </div>
           <div class="sr-group">
             <div class="__srgi">
               <div class="__srgi-title">
                 <a href="https://example.com/two">Grouped Result</a>
               </div>
-              <div class="__sri-desc">Second snippet</div>
+              <div class="__sri-desc"><div>
+                <span class="__sri-time"> Mar 3, 2024 </span> Second
+                snippet <a class="_0_summarize_page summarize-link" href="/summarizer?url=x">Summarize</a>
+              </div></div>
             </div>
           </div>
         </body></html>
@@ -671,15 +733,47 @@ mod tests {
 
         let results = parse_search_results(html).expect("parser should succeed");
 
-        assert_eq!(results.len(), 2);
-        assert_eq!(results[0].t, 0);
-        assert_eq!(results[0].title, "One Result");
-        assert_eq!(results[0].url, "https://example.com/one");
-        assert_eq!(results[0].snippet, "First snippet");
-        assert_eq!(results[1].t, 0);
-        assert_eq!(results[1].title, "Grouped Result");
-        assert_eq!(results[1].url, "https://example.com/two");
-        assert_eq!(results[1].snippet, "Second snippet");
+        let summary = results
+            .iter()
+            .map(|result| {
+                (
+                    result.title.as_str(),
+                    result.url.as_str(),
+                    result.snippet.as_str(),
+                    result.published.as_deref(),
+                )
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            summary,
+            [
+                (
+                    "One Result",
+                    "https://example.com/one",
+                    "First snippet.",
+                    Some("2026-10-04T00:00:00Z")
+                ),
+                (
+                    "Undated Result",
+                    "https://example.com/undated",
+                    "No date here.",
+                    None
+                ),
+                (
+                    "Relative Result",
+                    "https://example.com/relative",
+                    "Yesterday Recent.",
+                    None
+                ),
+                (
+                    "Grouped Result",
+                    "https://example.com/two",
+                    "Second snippet",
+                    Some("2024-03-03T00:00:00Z")
+                ),
+            ]
+        );
+        assert!(results.iter().all(|result| result.t == 0));
     }
 
     #[test]