kiromi-ai-cli 0.2.2

// SPDX-License-Identifier: Apache-2.0 OR MIT
//! Top-level clap derive surface.

use std::path::PathBuf;

use clap::{Args, Parser, Subcommand};

/// `kiromi-ai` — operator/dev CLI for the kiromi-ai-memory memory store.
#[derive(Debug, Parser)]
#[command(name = "kiromi-ai", version, about, long_about = None)]
pub(crate) struct Cli {
    /// Globals shared by every subcommand.
    #[command(flatten)]
    pub(crate) globals: GlobalArgs,

    /// Subcommand to run.
    #[command(subcommand)]
    pub(crate) command: Command,
}

/// Globals shared by every subcommand.
#[derive(Debug, Args, Clone)]
pub(crate) struct GlobalArgs {
    /// Path to the config file. Defaults to the per-OS user config dir.
    #[arg(long, env = "KIROMI_AI_CONFIG", global = true)]
    pub(crate) config: Option<PathBuf>,

    /// Storage URI (e.g. `local:./store`, `memory:`).
    #[arg(long, env = "KIROMI_AI_STORAGE", global = true)]
    pub(crate) storage: Option<String>,

    /// Metadata URI (e.g. `sqlite:./store/metadata.db`, `sqlite::memory:`).
    #[arg(long, env = "KIROMI_AI_METADATA", global = true)]
    pub(crate) metadata: Option<String>,

    /// Tenant id.
    #[arg(long, env = "KIROMI_AI_TENANT", global = true)]
    pub(crate) tenant: Option<String>,

    /// Partition scheme template.
    #[arg(long, env = "KIROMI_AI_SCHEME", global = true)]
    pub(crate) scheme: Option<String>,

    /// Embedder family (e.g. `onnx`, `mock`).
    #[arg(
        long = "embedder-family",
        env = "KIROMI_AI_EMBEDDER_FAMILY",
        global = true
    )]
    pub(crate) embedder_family: Option<String>,

    /// Embedder config as raw JSON (`'{"model":"..."}'`) or `@path/to/cfg.json`.
    #[arg(
        long = "embedder-config",
        env = "KIROMI_AI_EMBEDDER_CONFIG",
        global = true
    )]
    pub(crate) embedder_config: Option<String>,

    /// Disable engine-side embedding. Append must then carry `--embedding`.
    #[arg(long = "no-embedder", env = "KIROMI_AI_NO_EMBEDDER", global = true)]
    pub(crate) no_embedder: bool,

    /// Audit-log actor field.
    #[arg(long, env = "KIROMI_AI_ACTOR", global = true)]
    pub(crate) actor: Option<String>,

    /// Emit machine-readable JSON instead of human-readable tables.
    #[arg(long, env = "KIROMI_AI_JSON", global = true)]
    pub(crate) json: bool,

    /// Increase log verbosity. `-v` = debug, `-vv` = trace.
    #[arg(short, long, action = clap::ArgAction::Count, global = true)]
    pub(crate) verbose: u8,
}

/// Top-level subcommand.
#[derive(Debug, Subcommand)]
pub(crate) enum Command {
    /// Initialise a fresh store: write `schema_meta`, validate connectivity.
    Init(InitArgs),
    /// Append a memory to a partition.
    Append(AppendArgs),
    /// Fetch a single memory.
    Get(GetArgs),
    /// List memories under a partition.
    List(ListArgs),
    /// Search across memories.
    Search(SearchArgs),
    /// Same-leaf related lookup.
    Related(RelatedArgs),
    /// Manage explicit links.
    #[command(subcommand)]
    Link(LinkCmd),
    /// Soft-delete a single memory.
    Delete(DeleteArgs),
    /// Soft-delete every memory under a partition.
    #[command(name = "delete-partition")]
    DeletePartition(DeletePartitionArgs),
    /// Dump SQL + audit-log rows for a memory or partition.
    Inspect(InspectArgs),
    /// Copy every live memory under a partition to a directory.
    Export(ExportArgs),
    /// Manage typed memory metadata attributes (Plan 11).
    #[command(subcommand)]
    Attribute(AttributeCmd),
    /// Manage point-in-time snapshots (Plan 12).
    #[command(subcommand)]
    Snapshot(SnapshotCmd),
    /// Reindex / regenerate-embeddings / list-stale subjects (Plan 12).
    #[command(subcommand)]
    Regenerate(RegenerateCmd),
    /// Repartition the store under a new partition scheme (Plan 12).
    #[command(name = "migrate-scheme")]
    MigrateScheme(MigrateSchemeArgs),
    /// Reap orphan blobs after a retention window (Plan 12).
    Gc(GcArgs),
    /// Assemble a token-budget-bounded context block list (Plan 12).
    Context(ContextArgs),
}

/// `snapshot` subcommand variants (Plan 12).
#[derive(Debug, Subcommand)]
pub(crate) enum SnapshotCmd {
    /// Take a fresh snapshot.
    Create(SnapshotCreateArgs),
    /// List every known snapshot.
    List,
    /// Delete a snapshot row (manifest blob is reaped by `gc`).
    Delete(SnapshotDeleteArgs),
    /// Restore the live set to a snapshot.
    Restore(SnapshotRestoreArgs),
}

/// `snapshot create` args.
#[derive(Debug, Args)]
pub(crate) struct SnapshotCreateArgs {
    /// Optional human tag.
    #[arg(long)]
    pub(crate) tag: Option<String>,
    /// Optional human reason.
    #[arg(long)]
    pub(crate) reason: Option<String>,
}

/// `snapshot delete` args.
#[derive(Debug, Args)]
pub(crate) struct SnapshotDeleteArgs {
    /// Snapshot id (ULID).
    pub(crate) id: String,
}

/// `snapshot restore` args.
#[derive(Debug, Args)]
pub(crate) struct SnapshotRestoreArgs {
    /// Snapshot id (ULID).
    pub(crate) id: String,
    /// Skip the typed-attribute round-trip.
    #[arg(long = "no-attributes")]
    pub(crate) no_attributes: bool,
}

/// `regenerate` subcommand variants (Plan 12).
#[derive(Debug, Subcommand)]
pub(crate) enum RegenerateCmd {
    /// Re-embed every live memory under the supplied scope.
    Embeddings(RegenerateEmbeddingsArgs),
    /// List subjects whose summary is stale (or every subject under
    /// `--scope` when `--force` is set).
    #[command(name = "summaries-list")]
    SummariesList(RegenerateSummariesListArgs),
    /// Cheap rebuild of vector + lexical indices.
    Reindex(ReindexArgs),
}

/// Common scope flag.
#[derive(Debug, Args)]
pub(crate) struct ScopeArg {
    /// Scope: `all`, `tenant`, or `partition=<path>`.
    #[arg(long, default_value = "all")]
    pub(crate) scope: String,
}

/// `regenerate embeddings` args.
#[derive(Debug, Args)]
pub(crate) struct RegenerateEmbeddingsArgs {
    #[command(flatten)]
    pub(crate) scope: ScopeArg,
}

/// `regenerate summaries-list` args.
#[derive(Debug, Args)]
pub(crate) struct RegenerateSummariesListArgs {
    #[command(flatten)]
    pub(crate) scope: ScopeArg,
    /// Yield every subject under scope regardless of stale flag.
    #[arg(long)]
    pub(crate) force: bool,
    /// Style filter — `compact` or `detailed`.
    #[arg(long, default_value = "compact")]
    pub(crate) style: String,
}

/// `regenerate reindex` args.
#[derive(Debug, Args)]
pub(crate) struct ReindexArgs {
    #[command(flatten)]
    pub(crate) scope: ScopeArg,
}

/// `migrate-scheme` args.
#[derive(Debug, Args)]
pub(crate) struct MigrateSchemeArgs {
    /// New partition scheme template.
    #[arg(long = "new-scheme")]
    pub(crate) new_scheme: String,
    /// Mapper binary — receives JSON memory records on stdin (one per
    /// line) and emits JSON `{"partitions": {"k": "v", ...}}` lines.
    #[arg(long = "mapper-binary")]
    pub(crate) mapper_binary: std::path::PathBuf,
    /// Dry run.
    #[arg(long)]
    pub(crate) dry_run: bool,
    /// Skip the pre-migration snapshot.
    #[arg(long = "no-snapshot")]
    pub(crate) no_snapshot: bool,
    /// Memories per checkpoint batch.
    #[arg(long = "batch-size", default_value_t = 64)]
    pub(crate) batch_size: u32,
}

/// `gc` args.
#[derive(Debug, Args)]
pub(crate) struct GcArgs {
    /// Retention window (e.g. `24h`, `0`).
    #[arg(long = "retain-for", default_value = "24h")]
    pub(crate) retain_for: String,
    /// Dry run.
    #[arg(long)]
    pub(crate) dry_run: bool,
}

/// `context` args.
#[derive(Debug, Args)]
pub(crate) struct ContextArgs {
    /// Focus node — `memory:<id>:<partition>` or `partition:<path>`.
    #[arg(long)]
    pub(crate) focus: String,
    /// Token budget.
    #[arg(long, default_value_t = 4_000)]
    pub(crate) budget: u32,
    /// Top-K memories to include for partition focus.
    #[arg(long = "top-k", default_value_t = 5)]
    pub(crate) top_k: u32,
    /// Include the tenant memo block.
    #[arg(long, default_value_t = true)]
    pub(crate) memo: bool,
}

/// `attribute` subcommand variants (Plan 11).
#[derive(Debug, Subcommand)]
pub(crate) enum AttributeCmd {
    /// Set one attribute on a memory.
    Set(AttrSetArgs),
    /// Read one attribute.
    Get(AttrGetArgs),
    /// Clear one attribute.
    Clear(AttrClearArgs),
    /// List every attribute on a memory.
    List(AttrListArgs),
    /// Find memory ids by exact (key, value) match.
    Find(AttrFindArgs),
    /// Find memory ids by inclusive `[min, max]` range on `(key, value)`.
    FindRange(AttrFindRangeArgs),
}

/// Shared kind tag for attribute CLI args.
#[derive(Debug, Args, Clone)]
pub(crate) struct AttrKindArg {
    /// Value kind: `string`, `int`, `decimal`, `bool`, `timestamp`, or `array`.
    /// `array` parses `--value` as a JSON array of typed values.
    #[arg(long, default_value = "string")]
    pub(crate) kind: String,
}

/// `attribute set` args.
#[derive(Debug, Args)]
pub(crate) struct AttrSetArgs {
    /// Memory id.
    #[arg(long)]
    pub(crate) memory: String,
    /// Attribute key.
    #[arg(long)]
    pub(crate) key: String,
    /// Attribute value (parsed against `--kind`).
    #[arg(long)]
    pub(crate) value: String,
    #[command(flatten)]
    pub(crate) kind: AttrKindArg,
}

/// `attribute get` args.
#[derive(Debug, Args)]
pub(crate) struct AttrGetArgs {
    /// Memory id.
    #[arg(long)]
    pub(crate) memory: String,
    /// Attribute key.
    #[arg(long)]
    pub(crate) key: String,
}

/// `attribute clear` args.
#[derive(Debug, Args)]
pub(crate) struct AttrClearArgs {
    /// Memory id.
    #[arg(long)]
    pub(crate) memory: String,
    /// Attribute key.
    #[arg(long)]
    pub(crate) key: String,
}

/// `attribute list` args.
#[derive(Debug, Args)]
pub(crate) struct AttrListArgs {
    /// Memory id.
    #[arg(long)]
    pub(crate) memory: String,
}

/// `attribute find` args.
#[derive(Debug, Args)]
pub(crate) struct AttrFindArgs {
    /// Attribute key.
    #[arg(long)]
    pub(crate) key: String,
    /// Attribute value (parsed against `--kind`).
    #[arg(long)]
    pub(crate) value: String,
    #[command(flatten)]
    pub(crate) kind: AttrKindArg,
}

/// `attribute find-range` args.
#[derive(Debug, Args)]
pub(crate) struct AttrFindRangeArgs {
    /// Attribute key.
    #[arg(long)]
    pub(crate) key: String,
    /// Inclusive minimum.
    #[arg(long)]
    pub(crate) min: String,
    /// Inclusive maximum.
    #[arg(long)]
    pub(crate) max: String,
    /// Kind: `int`, `decimal`, or `timestamp`.
    #[arg(long, default_value = "int")]
    pub(crate) kind: String,
}

/// `init` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct InitArgs {
    /// Force re-initialise. Slice 1: errors on existing store.
    #[arg(long)]
    pub(crate) force: bool,
}

/// `append` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct AppendArgs {
    /// `key=value,key=value` partition selector.
    #[arg(long)]
    pub(crate) partition: String,

    /// Read content from this file. Conflicts with `--stdin` and `--message`.
    #[arg(long, conflicts_with_all = ["stdin", "message"])]
    pub(crate) file: Option<PathBuf>,

    /// Read content from stdin.
    #[arg(long, conflicts_with_all = ["file", "message"])]
    pub(crate) stdin: bool,

    /// Inline message text. Conflicts with `--file` / `--stdin`.
    #[arg(long, conflicts_with_all = ["file", "stdin"])]
    pub(crate) message: Option<String>,

    /// Content kind. `md` (default) or `txt`.
    #[arg(long, default_value = "md")]
    pub(crate) kind: String,

    /// Path to a JSON file containing a `Vec<f32>`. Required when
    /// `--no-embedder` is set.
    #[arg(long)]
    pub(crate) embedding: Option<PathBuf>,

    /// Explicit links — repeatable. Each value is a memory id (ULID).
    #[arg(long = "link", value_name = "MEMORY_ID")]
    pub(crate) links: Vec<String>,
}

/// `get` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct GetArgs {
    /// Memory id (ULID).
    pub(crate) id: String,
}

/// `list` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct ListArgs {
    /// `key=value,...` partition selector.
    #[arg(long)]
    pub(crate) partition: String,

    /// Page size.
    #[arg(long, default_value_t = 50)]
    pub(crate) limit: u32,

    /// Continuation cursor returned by a prior page.
    #[arg(long)]
    pub(crate) cursor: Option<String>,

    /// Include soft-tombstoned memories.
    #[arg(long = "include-tombstoned")]
    pub(crate) include_tombstoned: bool,
}

/// `search` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct SearchArgs {
    /// Query text.
    pub(crate) query: String,

    /// Pure semantic search.
    #[arg(long, conflicts_with_all = ["text", "hybrid"])]
    pub(crate) semantic: bool,
    /// Pure lexical search.
    #[arg(long, conflicts_with_all = ["semantic", "hybrid"])]
    pub(crate) text: bool,
    /// Hybrid (default).
    #[arg(long, conflicts_with_all = ["semantic", "text"])]
    pub(crate) hybrid: bool,

    /// Hybrid alpha (0.0–1.0). Ignored unless `--hybrid`.
    #[arg(long)]
    pub(crate) alpha: Option<f32>,

    /// Top-K hits to return.
    #[arg(long, default_value_t = 10)]
    pub(crate) top: usize,

    /// Restrict the search to one partition (full path).
    #[arg(long)]
    pub(crate) within: Option<String>,
}

/// `related` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct RelatedArgs {
    /// Memory id (ULID).
    pub(crate) id: String,
    /// Top-K neighbours.
    #[arg(long, default_value_t = 5)]
    pub(crate) top: usize,
}

/// `link` subcommand variants.
#[derive(Debug, Subcommand)]
pub(crate) enum LinkCmd {
    /// Add a `src → dst` link (and the implicit reverse).
    Add {
        /// Source memory id.
        src: String,
        /// Destination memory id.
        dst: String,
    },
    /// Remove a link.
    Remove {
        /// Source memory id.
        src: String,
        /// Destination memory id.
        dst: String,
    },
    /// List all links sourced at a memory.
    List {
        /// Memory id (ULID).
        id: String,
    },
}

/// `delete` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct DeleteArgs {
    /// Memory id (ULID).
    pub(crate) id: String,
}

/// `delete-partition` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct DeletePartitionArgs {
    /// Full partition path, e.g. `user=alex/year=2026/month=05/topic=meetings`.
    pub(crate) path: String,
}

/// `inspect` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct InspectArgs {
    /// Inspect a single memory.
    #[arg(long, conflicts_with = "partition")]
    pub(crate) memory: Option<String>,
    /// Inspect a partition.
    #[arg(long, conflicts_with = "memory")]
    pub(crate) partition: Option<String>,
}

/// `export` subcommand args.
#[derive(Debug, Args)]
pub(crate) struct ExportArgs {
    /// Partition selector.
    #[arg(long)]
    pub(crate) partition: String,
    /// Destination directory (created if absent).
    #[arg(long)]
    pub(crate) to: PathBuf,
}