Trait EngineApi 

pub trait EngineApi: Send + Sync {
    // Required methods
    fn run<'life0, 'async_trait>(
        &'life0 self,
        code: Option<String>,
        code_file: Option<String>,
        ctx: Option<Value>,
        project_root: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn advice<'life0, 'life1, 'async_trait>(
        &'life0 self,
        strategy: &'life1 str,
        task: Option<String>,
        opts: Option<Value>,
        project_root: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn continue_single<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        response: String,
        query_id: Option<&'life2 str>,
        usage: Option<TokenUsage>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn continue_batch<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        responses: Vec<QueryResponse>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn status<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: Option<&'life1 str>,
        pending_filter: Option<Value>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn eval<'life0, 'life1, 'async_trait>(
        &'life0 self,
        scenario: Option<String>,
        scenario_file: Option<String>,
        scenario_name: Option<String>,
        strategy: &'life1 str,
        strategy_opts: Option<Value>,
        auto_card: bool,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn eval_history<'life0, 'life1, 'async_trait>(
        &'life0 self,
        strategy: Option<&'life1 str>,
        limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn eval_detail<'life0, 'life1, 'async_trait>(
        &'life0 self,
        eval_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn eval_compare<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        eval_id_a: &'life1 str,
        eval_id_b: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn scenario_list<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn scenario_show<'life0, 'life1, 'async_trait>(
        &'life0 self,
        name: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn scenario_install<'life0, 'async_trait>(
        &'life0 self,
        url: String,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pkg_link<'life0, 'async_trait>(
        &'life0 self,
        path: String,
        name: Option<String>,
        force: Option<bool>,
        scope: Option<String>,
        project_root: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pkg_list<'life0, 'async_trait>(
        &'life0 self,
        project_root: Option<String>,
        limit: Option<i32>,
        sort: Option<String>,
        filter: Option<Value>,
        fields: Option<Vec<String>>,
        verbose: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pkg_install<'life0, 'async_trait>(
        &'life0 self,
        url: String,
        name: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pkg_unlink<'life0, 'async_trait>(
        &'life0 self,
        name: String,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pkg_remove<'life0, 'life1, 'async_trait>(
        &'life0 self,
        name: &'life1 str,
        project_root: Option<String>,
        version: Option<String>,
        scope: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn pkg_repair<'life0, 'async_trait>(
        &'life0 self,
        name: Option<String>,
        project_root: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pkg_doctor<'life0, 'async_trait>(
        &'life0 self,
        name: Option<String>,
        project_root: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn add_note<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        session_id: &'life1 str,
        content: &'life2 str,
        title: Option<&'life3 str>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait;
    fn log_view<'life0, 'life1, 'async_trait>(
        &'life0 self,
        session_id: Option<&'life1 str>,
        limit: Option<usize>,
        max_chars: Option<usize>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn stats<'life0, 'life1, 'async_trait>(
        &'life0 self,
        strategy_filter: Option<&'life1 str>,
        days: Option<u64>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn init<'life0, 'async_trait>(
        &'life0 self,
        project_root: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn update<'life0, 'async_trait>(
        &'life0 self,
        project_root: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn migrate<'life0, 'async_trait>(
        &'life0 self,
        project_root: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn card_list<'life0, 'async_trait>(
        &'life0 self,
        pkg: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn card_get<'life0, 'life1, 'async_trait>(
        &'life0 self,
        card_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn card_find<'life0, 'async_trait>(
        &'life0 self,
        pkg: Option<String>,
        where_: Option<Value>,
        order_by: Option<Value>,
        limit: Option<usize>,
        offset: Option<usize>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn card_alias_list<'life0, 'async_trait>(
        &'life0 self,
        pkg: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn card_get_by_alias<'life0, 'life1, 'async_trait>(
        &'life0 self,
        name: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn card_alias_set<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        name: &'life1 str,
        card_id: &'life2 str,
        pkg: Option<String>,
        note: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn card_append<'life0, 'life1, 'async_trait>(
        &'life0 self,
        card_id: &'life1 str,
        fields: Value,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn card_install<'life0, 'async_trait>(
        &'life0 self,
        url: String,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn card_samples<'life0, 'life1, 'async_trait>(
        &'life0 self,
        card_id: &'life1 str,
        offset: Option<usize>,
        limit: Option<usize>,
        where_: Option<Value>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn card_lineage<'life0, 'life1, 'async_trait>(
        &'life0 self,
        card_id: &'life1 str,
        direction: Option<String>,
        depth: Option<usize>,
        include_stats: Option<bool>,
        relation_filter: Option<Vec<String>>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn hub_reindex<'life0, 'async_trait>(
        &'life0 self,
        output_path: Option<String>,
        source_dir: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn hub_gendoc<'life0, 'async_trait>(
        &'life0 self,
        source_dir: String,
        out_dir: Option<String>,
        projections: Option<Vec<String>>,
        config_path: Option<String>,
        lint_strict: Option<bool>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn hub_dist<'life0, 'async_trait>(
        &'life0 self,
        source_dir: String,
        output_path: Option<String>,
        out_dir: Option<String>,
        preset: Option<String>,
        project_root: Option<String>,
        projections: Option<Vec<String>>,
        config_path: Option<String>,
        lint_strict: Option<bool>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn hub_info<'life0, 'async_trait>(
        &'life0 self,
        pkg: String,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn hub_search<'life0, 'async_trait>(
        &'life0 self,
        query: Option<String>,
        category: Option<String>,
        installed_only: Option<bool>,
        limit: Option<i32>,
        sort: Option<String>,
        filter: Option<Value>,
        fields: Option<Vec<String>>,
        verbose: Option<String>,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn info<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = String> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided method
    fn card_sink_backfill<'life0, 'async_trait>(
        &'life0 self,
        _sink: String,
        _dry_run: bool,
    ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

Transport-independent API for the algocline engine.

Abstracts the full public surface of AppService so that callers (MCP handler, future daemon client, etc.) can operate through Arc<dyn EngineApi> without depending on the concrete implementation.

All methods are async to support both local (in-process) and remote (socket/HTTP) implementations uniformly.

Required Methods

fn run<'life0, 'async_trait>( &'life0 self, code: Option<String>, code_file: Option<String>, ctx: Option<Value>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Execute Lua code with optional JSON context.

fn advice<'life0, 'life1, 'async_trait>( &'life0 self, strategy: &'life1 str, task: Option<String>, opts: Option<Value>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Apply an installed strategy package. Task is optional.

fn continue_single<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, response: String, query_id: Option<&'life2 str>, usage: Option<TokenUsage>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Continue a paused execution — single response (with optional query_id).

fn continue_batch<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, responses: Vec<QueryResponse>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Continue a paused execution — batch feed.

fn status<'life0, 'life1, 'async_trait>( &'life0 self, session_id: Option<&'life1 str>, pending_filter: Option<Value>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Query active session status.

pending_filter is a free-form JSON value forwarded from MCP callers, decoded inside the app layer into either a preset name ("meta" / "preview" / "full") or a custom field-filter object. None keeps the legacy count-only snapshot.

fn eval<'life0, 'life1, 'async_trait>( &'life0 self, scenario: Option<String>, scenario_file: Option<String>, scenario_name: Option<String>, strategy: &'life1 str, strategy_opts: Option<Value>, auto_card: bool, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run an evalframe evaluation suite.

auto_card: when true, emit an immutable Card (~/.algocline/cards/{strategy}/{card_id}.toml) summarizing the run.

fn eval_history<'life0, 'life1, 'async_trait>( &'life0 self, strategy: Option<&'life1 str>, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

List eval history, optionally filtered by strategy.

fn eval_detail<'life0, 'life1, 'async_trait>( &'life0 self, eval_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

View a specific eval result by ID.

fn eval_compare<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, eval_id_a: &'life1 str, eval_id_b: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Compare two eval results with statistical significance testing.

fn scenario_list<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List available scenarios.

fn scenario_show<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Show the content of a named scenario.

fn scenario_install<'life0, 'async_trait>( &'life0 self, url: String, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Install scenarios from a Git URL or local path.

fn pkg_link<'life0, 'async_trait>( &'life0 self, path: String, name: Option<String>, force: Option<bool>, scope: Option<String>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Link a local directory as a project-local package (symlink to cache).

Scope selection:

• scope = None or Some("global") — symlink into ~/.algocline/packages/ (visible to all projects).
• scope = Some("variant") — record the path in alc.local.toml at the project root (worktree-scoped override, git-ignored). No symlink is created.
• Any other value → Err("invalid scope: ...").

project_root is only consulted when scope = Some("variant"). If None, falls back to ALC_PROJECT_ROOT env or ancestor walk from cwd.

fn pkg_list<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, limit: Option<i32>, sort: Option<String>, filter: Option<Value>, fields: Option<Vec<String>>, verbose: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List installed packages with metadata.

When project_root is provided, project-local packages from alc.toml/alc.lock are included with scope: "project". Global packages carry scope: "global".

Mirrors the list-tool knob contract used by Self::hub_search (plan.md §4.1). Parameters are individual JSON-primitive Option<T> values so the algocline-core crate stays free of algocline-app-internal types; the impl folds them into its pub(crate) ListOpts struct.

• limit is Option<i32> at this layer (MCP/JSON boundary). The impl clamps negative values to 0 and casts to usize. Some(0) (and thus clamped negatives) means no limit (return all entries — empty-means-all idiom); None falls back to the tool’s default cap.
• filter is a free-form JSON object; it is Deserialized into a HashMap<String, Value> inside the app layer. Non-object values are logged via tracing::warn and treated as no filter.
• fields / verbose drive projection on each entry of the packages array; fields wins when both are supplied.
• Top-level keys (packages, search_paths, project_root, lockfile_path) are never projected away.

fn pkg_install<'life0, 'async_trait>( &'life0 self, url: String, name: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Install a package from a Git URL or local path.

fn pkg_unlink<'life0, 'async_trait>( &'life0 self, name: String, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Remove a symlinked package from ~/.algocline/packages/.

Only removes symlinks; for installed (copied) packages, use pkg_remove.

fn pkg_remove<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, project_root: Option<String>, version: Option<String>, scope: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove a package entry, scoped by scope ("project" / "global" / "all", default "project").

• "project": remove from alc.toml + alc.lock. Requires an alc.toml via project_root or ancestor walk.
• "global": remove from ~/.algocline/installed.json only. project_root is ignored.
• "all": remove from both; succeeds if either scope had the entry.

Physical files in ~/.algocline/packages/{name}/ are never deleted.

fn pkg_repair<'life0, 'async_trait>( &'life0 self, name: Option<String>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Heal broken package state by reinstalling entries whose installed directory is missing. Other broken kinds (dangling symlink, declared-path missing) are surfaced as unrepairable with a suggested remediation.

fn pkg_doctor<'life0, 'async_trait>( &'life0 self, name: Option<String>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Diagnose package state without side effects.

Read-only counterpart of Self::pkg_repair. Classifies packages into four buckets — healthy, installed_missing, symlink_dangling, path_missing — and returns the result as a JSON string. No filesystem writes, no pkg_install calls.

name restricts the report to a single package; None inspects every known package. project_root is used for the alc.toml / alc.local.toml pass (falls back to ancestor walk from cwd).

fn add_note<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, session_id: &'life1 str, content: &'life2 str, title: Option<&'life3 str>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Append a note to a session’s log file.

fn log_view<'life0, 'life1, 'async_trait>( &'life0 self, session_id: Option<&'life1 str>, limit: Option<usize>, max_chars: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

View session logs.

fn stats<'life0, 'life1, 'async_trait>( &'life0 self, strategy_filter: Option<&'life1 str>, days: Option<u64>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Aggregate stats across all logged sessions.

fn init<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Initialize alc.toml in the given project root.

Creates a minimal alc.toml ([packages] section only). Fails if alc.toml already exists (no overwrite).

fn update<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Re-resolve all alc.toml entries and rewrite alc.lock.

Requires an alc.toml to be present. Returns resolved count and errors.

fn migrate<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Migrate a legacy alc.lock to alc.toml + new alc.lock format.

Detects legacy format via linked_at / local_dir fields. Backs up the old lock file as alc.lock.bak.

fn card_list<'life0, 'async_trait>( &'life0 self, pkg: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List Card summaries, optionally filtered by pkg.

fn card_get<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetch a full Card by id.

fn card_find<'life0, 'async_trait>( &'life0 self, pkg: Option<String>, where_: Option<Value>, order_by: Option<Value>, limit: Option<usize>, offset: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Filter/sort Cards using the Prisma-style where DSL.

• pkg: restricts filesystem scan to a single pkg subdir (I/O hint).
• where_: nested-object predicate (see card::parse_where).
• order_by: array of dotted-path sort keys; - prefix = desc.
• limit / offset: pagination.

fn card_alias_list<'life0, 'async_trait>( &'life0 self, pkg: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List aliases, optionally filtered by pkg.

fn card_get_by_alias<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resolve an alias name to its bound Card and return the full Card JSON.

fn card_alias_set<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, name: &'life1 str, card_id: &'life2 str, pkg: Option<String>, note: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Bind (or rebind) an alias to a Card.

fn card_append<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, fields: Value, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Append new top-level fields to an existing Card (additive-only).

fn card_install<'life0, 'async_trait>( &'life0 self, url: String, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Install Cards from a Card Collection repo (Git URL or local path).

fn card_samples<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, offset: Option<usize>, limit: Option<usize>, where_: Option<Value>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read per-case samples from a Card’s sidecar JSONL file.

where_ applies the same Prisma-style DSL used by card_find to each sample row; offset/limit page the post-filter stream.

fn card_lineage<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, direction: Option<String>, depth: Option<usize>, include_stats: Option<bool>, relation_filter: Option<Vec<String>>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Walk a Card’s lineage tree via metadata.prior_card_id.

• direction: "up" | "down" | "both" (default "up").
• depth: max traversal depth (default 10).
• include_stats: include each node’s [stats] section.
• relation_filter: optional list of accepted prior_relation values.

fn hub_reindex<'life0, 'async_trait>( &'life0 self, output_path: Option<String>, source_dir: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Rebuild hub index from a packages directory.

When source_dir is provided, scans that directory directly (pure metadata, no manifest). When omitted, scans ~/.algocline/packages/.

fn hub_gendoc<'life0, 'async_trait>( &'life0 self, source_dir: String, out_dir: Option<String>, projections: Option<Vec<String>>, config_path: Option<String>, lint_strict: Option<bool>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Generate human-readable documentation artifacts from a hub index.

Runs the embedded Lua gen_docs pipeline (originally shipped with algocline-bundled-packages) against source_dir, which must contain a fresh hub_index.json. Emits narrative/{pkg}.md, llms.txt, llms-full.txt under out_dir (defaults to {source_dir}/docs), plus optional projections depending on projections:

• "hub" → {out_dir}/hub/{pkg}.json
• "context7" → {source_dir}/context7.json (requires config_path)
• "devin" → {source_dir}/.devin/wiki.json (requires config_path)
• "lint" → run V0 lint pass (warnings only)
• "lint_only" → run lint, skip file generation

config_path points at a TOML file with top-level [context7] / [devin] tables. It is required only when projections includes "context7" or "devin".

Projection names are validated strictly and unknown values are rejected with Err("gendoc: unknown projection ...").

lint_strict = true upgrades lint errors to a hard failure (equivalent to the --strict CLI flag).

Returns a JSON string containing the collected stdout / stderr plus the resolved source_dir / out_dir for observability.

fn hub_dist<'life0, 'async_trait>( &'life0 self, source_dir: String, output_path: Option<String>, out_dir: Option<String>, preset: Option<String>, project_root: Option<String>, projections: Option<Vec<String>>, config_path: Option<String>, lint_strict: Option<bool>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Run hub_reindex followed by hub_gendoc as a single facade.

This is a convenience wrapper for downstream hub repositories that want to regenerate the index and the public docs in one call. The composed response is a JSON object:

{
  "reindex": <hub_reindex response>,
  "gendoc": <hub_gendoc response>,
  "preset_catalog_version": "...",
  "preset": { "name": ..., "catalog_version": ..., "resolved": { ... } }
}

Error propagation:

• If hub_reindex fails, hub_dist returns immediately with Err("dist: reindex failed: {inner}") and does not invoke hub_gendoc.
• If hub_gendoc fails, the error text includes the reindex JSON that already succeeded: Err("dist: gendoc failed: {inner}\nreindex result (succeeded): {json}"). The reindex-side side effects (written hub_index.json) are not rolled back.

output_path is the hub_index.json destination (reindex arg). Callers typically pass {source_dir}/hub_index.json so the subsequent gendoc step can read it back.

Presets (preset) are expanded inside hub_dist into primitive hub_gendoc arguments (projections / config_path / lint_strict). When preset is set, the successful JSON response includes a preset object with catalog_version plus the fully resolved knobs for observability.

Merge order (strongest wins):

1. explicit MCP arguments (projections / config_path / lint_strict)
2. optional alc.toml overrides under [hub.dist.presets.<name>] (keyed by project_root) — only fills omitted knobs
3. builtin Current defaults for the selected preset

fn hub_info<'life0, 'async_trait>( &'life0 self, pkg: String, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Show detailed information for a single package.

fn hub_search<'life0, 'async_trait>( &'life0 self, query: Option<String>, category: Option<String>, installed_only: Option<bool>, limit: Option<i32>, sort: Option<String>, filter: Option<Value>, fields: Option<Vec<String>>, verbose: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Search packages across remote index + local install state.

This trait method mirrors the MCP alc_hub_search tool. Parameters are deliberately individual JSON-primitive Option<T> values (rather than an aggregate struct) so that the algocline-core crate stays free of algocline-app-internal types (see plan.md §4.1). The algocline-app side of the impl folds these into its pub(crate) ListOpts struct.

• limit is Option<i32> at this layer (MCP/JSON boundary). The impl casts to usize internally.
• filter is a free-form JSON object; it is Deserialized into a HashMap<String, Value> inside the app layer.
• fields / verbose drive projection; fields wins when both are supplied.

fn info<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = String> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Show server configuration and diagnostic info.

Provided Methods

fn card_sink_backfill<'life0, 'async_trait>( &'life0 self, _sink: String, _dry_run: bool, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Backfill one subscriber (sink URI) with all cards from the primary store. Drift-safe: cards already present on the sink are skipped (never overwritten). Returns a SinkBackfillReport serialized as a JSON string.

Implementors