khive-pack-session 0.13.0

Session verb pack - store/list/resume/export over the notes substrate
Documentation
//! Verb handlers for the session pack, one file per verb, plus shared
//! response shapes and the id-resolution helpers common to resume/export.

pub(crate) mod export;
pub(crate) mod list;
pub(crate) mod maintenance;
pub(crate) mod resume;
pub(crate) mod search;
pub(crate) mod store;

use std::str::FromStr;

use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use uuid::Uuid;

use khive_runtime::{micros_to_iso, KhiveRuntime, NamespaceToken, Resolved, RuntimeError};
use khive_storage::note::Note;

use crate::vocab::SESSION_KIND;

pub(crate) use khive_runtime::deser_params as deser;

/// Resolve the shared inclusive limit range; callers retain their error wording.
pub(crate) fn validate_limit(requested: Option<u32>, default: u32, max: u32) -> Result<u32, u32> {
    let limit = requested.unwrap_or(default);
    if (1..=max).contains(&limit) {
        Ok(limit)
    } else {
        Err(limit)
    }
}

#[derive(Debug, Serialize)]
pub(crate) struct SessionRecord {
    pub id: String,
    pub kind: &'static str,
    pub title: Option<String>,
    pub provider: Option<String>,
    pub provider_session_id: Option<String>,
    pub tags: Vec<String>,
    pub content: String,
    pub properties: Value,
    pub created_at: String,
    pub updated_at: String,
    pub namespace: String,
}

#[derive(Debug, Serialize)]
pub(crate) struct SessionSummary {
    pub id: String,
    pub full_id: String,
    pub kind: &'static str,
    pub title: Option<String>,
    pub provider: Option<String>,
    pub provider_session_id: Option<String>,
    pub tags: Vec<String>,
    pub created_at: String,
    pub updated_at: String,
    pub namespace: String,
}

#[derive(Debug, Serialize)]
pub(crate) struct StoreResult {
    pub ok: bool,
    pub session: SessionRecord,
}

#[derive(Debug, Serialize)]
pub(crate) struct ListResult {
    pub ok: bool,
    pub sessions: Vec<SessionSummary>,
    pub count: usize,
    pub total: Option<u64>,
    pub limit: u32,
    pub offset: u64,
}

#[derive(Debug, Serialize)]
pub(crate) struct ResumeResult {
    pub ok: bool,
    pub session: SessionRecord,
}

#[derive(Debug, Serialize)]
pub(crate) struct ExportJsonResult {
    pub ok: bool,
    pub format: &'static str,
    pub session: SessionRecord,
}

#[derive(Debug, Serialize)]
pub(crate) struct ExportMarkdownResult {
    pub ok: bool,
    pub format: &'static str,
    pub content: String,
}

fn string_property(properties: &Value, key: &str) -> Option<String> {
    properties
        .get(key)
        .and_then(|v| v.as_str())
        .map(String::from)
}

fn tags_property(properties: &Value) -> Vec<String> {
    match properties.get("tags").and_then(|v| v.as_array()) {
        Some(arr) => arr
            .iter()
            .filter_map(|v| v.as_str().map(String::from))
            .collect(),
        None => Vec::new(),
    }
}

pub(crate) fn to_session_record(note: &Note) -> SessionRecord {
    let properties = note.properties.clone().unwrap_or_else(|| json!({}));
    SessionRecord {
        id: note.id.as_hyphenated().to_string(),
        kind: SESSION_KIND,
        title: note.name.clone(),
        provider: string_property(&properties, "provider"),
        provider_session_id: string_property(&properties, "provider_session_id"),
        tags: tags_property(&properties),
        content: note.content.clone(),
        properties,
        created_at: micros_to_iso(note.created_at),
        updated_at: micros_to_iso(note.updated_at),
        namespace: note.namespace.clone(),
    }
}

pub(crate) fn to_session_summary(note: &Note) -> SessionSummary {
    let properties = note.properties.clone().unwrap_or_else(|| json!({}));
    SessionSummary {
        id: note.id.as_hyphenated().to_string(),
        full_id: note.id.as_hyphenated().to_string(),
        kind: SESSION_KIND,
        title: note.name.clone(),
        provider: string_property(&properties, "provider"),
        provider_session_id: string_property(&properties, "provider_session_id"),
        tags: tags_property(&properties),
        created_at: micros_to_iso(note.created_at),
        updated_at: micros_to_iso(note.updated_at),
        namespace: note.namespace.clone(),
    }
}

/// Resolve a caller-supplied id to a UUID: accepts a full UUID or an 8+ hex
/// short prefix, matching the runtime's `resolve_prefix` convention.
pub(crate) async fn resolve_session_uuid(
    runtime: &KhiveRuntime,
    token: &NamespaceToken,
    raw: &str,
    verb: &str,
) -> Result<Uuid, RuntimeError> {
    if let Ok(uuid) = Uuid::from_str(raw) {
        return Ok(uuid);
    }

    if raw.len() >= 8 && raw.chars().all(|c| c.is_ascii_hexdigit()) {
        return match runtime.resolve_prefix(token, raw).await? {
            Some(uuid) => Ok(uuid),
            None => Err(RuntimeError::InvalidInput(format!(
                "{verb}: id prefix {raw} matched no records; valid values: full UUID or 8+ hex prefix"
            ))),
        };
    }

    Err(RuntimeError::InvalidInput(format!(
        "{verb}: id must be a full UUID or 8+ hex prefix; valid values: full UUID or 8+ hex prefix; got {raw}"
    )))
}

/// Fetch a session note by resolved UUID, rejecting non-session note kinds
/// and non-note substrates.
pub(crate) async fn fetch_session_note(
    runtime: &KhiveRuntime,
    token: &NamespaceToken,
    id: Uuid,
    verb: &str,
) -> Result<Note, RuntimeError> {
    match runtime.resolve_primary(token, id).await? {
        Some(Resolved::Note(note)) if note.kind == SESSION_KIND => Ok(note),
        Some(Resolved::Note(note)) => Err(RuntimeError::InvalidInput(format!(
            "{verb}: expected note kind \"session\"; valid note kind: session; got {}",
            note.kind
        ))),
        Some(_) => Err(RuntimeError::InvalidInput(format!(
            "{verb}: id must resolve to a session note; valid substrate: note kind session"
        ))),
        None => Err(RuntimeError::NotFound(format!("session not found: {id}"))),
    }
}

/// Validate a caller-supplied optional string field: `None` passes through,
/// `Some` must be non-empty after trimming.
pub(crate) fn require_non_empty_if_present(
    value: &Option<String>,
    field: &str,
    verb: &str,
) -> Result<(), RuntimeError> {
    if let Some(s) = value {
        if s.trim().is_empty() {
            return Err(RuntimeError::InvalidInput(format!(
                "{verb}: {field} must be a non-empty string when provided"
            )));
        }
    }
    Ok(())
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct StoreParams {
    pub content: String,
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub provider: Option<String>,
    #[serde(default)]
    pub provider_session_id: Option<String>,
    #[serde(default)]
    pub tags: Option<Vec<String>>,
}

impl StoreParams {
    /// Shared pure creation validator for the specialized and generic writers.
    pub(crate) fn validate(&self, verb: &str) -> Result<(), RuntimeError> {
        if self.content.trim().is_empty() {
            return Err(RuntimeError::InvalidInput(format!(
                "{verb}: content must not be empty"
            )));
        }
        require_non_empty_if_present(&self.title, "title", verb)?;
        require_non_empty_if_present(&self.provider, "provider", verb)?;
        require_non_empty_if_present(&self.provider_session_id, "provider_session_id", verb)?;
        if self
            .tags
            .as_ref()
            .is_some_and(|tags| tags.iter().any(|tag| tag.trim().is_empty()))
        {
            return Err(RuntimeError::InvalidInput(format!(
                "{verb}: tags entries must be non-empty strings"
            )));
        }
        Ok(())
    }
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct ListParams {
    #[serde(default)]
    pub limit: Option<u32>,
    #[serde(default)]
    pub offset: Option<u32>,
    #[serde(default)]
    pub provider: Option<String>,
    #[serde(default)]
    pub agent_id: Option<String>,
    #[serde(default)]
    pub since: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct ResumeParams {
    pub id: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct ExportParams {
    pub id: String,
    #[serde(default)]
    pub format: Option<String>,
}