Struct AppService 

pub struct AppService { /* private fields */ }

Implementations

impl AppService

pub fn card_list(&self, pkg: Option<&str>) -> Result<String, String>

List Cards as JSON summaries, optionally filtered by package.

pub fn card_get(&self, card_id: &str) -> Result<String, String>

Fetch full Card body (Tier 1) by id.

pub fn card_find( &self, pkg: Option<String>, where_: Option<Value>, order_by: Option<Value>, limit: Option<usize>, offset: Option<usize>, ) -> Result<String, String>

Query Cards using the where DSL + order_by / limit / offset.

pub fn card_get_by_alias(&self, name: &str) -> Result<String, String>

Resolve alias then fetch the full Card.

pub fn card_alias_list(&self, pkg: Option<&str>) -> Result<String, String>

List aliases, optionally filtered by package.

pub fn card_alias_set( &self, name: &str, card_id: &str, pkg: Option<&str>, note: Option<&str>, ) -> Result<String, String>

Pin or rebind a mutable alias to a Card.

pub fn card_append( &self, card_id: &str, fields: Value, ) -> Result<String, String>

Additive-only annotation — new top-level keys only.

pub async fn card_install(&self, url: String) -> Result<String, String>

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

A Card Collection is identified by alc_cards.toml at the repo root. Each subdirectory is treated as a package name, and *.toml card files within are imported into ~/.algocline/cards/{pkg}/.

pub fn card_samples( &self, card_id: &str, offset: usize, limit: Option<usize>, where_: Option<Value>, ) -> Result<String, String>

Read per-case sidecar rows (Tier 2) with where filtering and paging.

pub fn card_lineage( &self, card_id: &str, direction: Option<&str>, depth: Option<usize>, include_stats: Option<bool>, relation_filter: Option<Vec<String>>, ) -> Result<String, String>

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

pub fn card_sink_backfill( &self, params: SinkBackfillParams, ) -> Result<String, String>

Backfill one subscriber (sink URI) with all cards from the primary store. Drift-safe: existing cards on the subscriber are skipped, never overwritten. Returns the card::SinkBackfillReport serialized as JSON for MCP transport.

impl AppService

pub async fn eval( &self, scenario: Option<String>, scenario_file: Option<String>, scenario_name: Option<String>, strategy: &str, strategy_opts: Option<Value>, auto_card: bool, ) -> Result<String, String>

Run an evalframe evaluation suite via alc.eval().

Resolves the scenario from one of three input modes (inline/file/name), injects the std global shim, and delegates to alc.eval() in prelude which handles evalframe loading, provider wiring, and optional Card emission.

Security: strategy is not sanitized

strategy is interpolated into a Lua string literal without escaping. This is intentional — algocline runs Lua in the caller’s own process with full ambient authority, so Lua injection does not cross a trust boundary.

pub fn eval_history( &self, strategy: Option<&str>, limit: usize, ) -> Result<String, String>

List eval history, optionally filtered by strategy.

pub fn eval_detail(&self, eval_id: &str) -> Result<String, String>

View a specific eval result by ID.

pub async fn eval_compare( &self, eval_id_a: &str, eval_id_b: &str, ) -> Result<String, String>

Compare two eval results with statistical significance testing.

Delegates to evalframe’s stats.welch_t (single source of truth for t-distribution table and test logic). Reads persisted aggregated.scores from each eval result — no re-computation of descriptive statistics.

The comparison result is persisted to ~/.algocline/evals/ so repeated lookups of the same pair are file reads only.

impl AppService

pub fn hub_reindex( &self, output_path: Option<&str>, source_dir: Option<&str>, ) -> Result<String, String>

Generate a hub index from a packages directory.

When source_dir is provided, scans that directory (e.g. a repo checkout) — pure metadata extraction, no manifest or card data mixed in. When omitted, scans ~/.algocline/packages/.

Writes the index to output_path (for CI / publishing). Does NOT touch the remote search cache.

pub fn hub_info(&self, pkg: &str) -> Result<String, String>

Show detailed information for a single package.

Aggregates package metadata (from index or local init.lua), all Cards, aliases, and eval stats into one response.

pub fn hub_search( &self, query: Option<&str>, category: Option<&str>, installed_only: Option<bool>, limit: Option<usize>, ) -> Result<String, String>

Search packages across remote indices + local state.

Index URLs are discovered from hub registries, manifest sources, and AUTO_INSTALL_SOURCES. Each source is cached independently.

impl AppService

pub async fn init(&self, project_root: Option<String>) -> Result<String, String>

impl AppService

pub async fn add_note( &self, session_id: &str, content: &str, title: Option<&str>, ) -> Result<String, String>

Append a note to a session’s log file.

pub async fn log_view( &self, session_id: Option<&str>, limit: Option<usize>, max_chars: Option<usize>, ) -> Result<String, String>

View session logs.

pub fn info(&self) -> String

Return diagnostic info about the current configuration (mise doctor style).

pub fn stats( &self, strategy_filter: Option<&str>, days: Option<u64>, ) -> Result<String, String>

Aggregate stats across all logged sessions.

Scans .meta.json files (with .json fallback for legacy logs). Optional filters: strategy (exact match), days (last N days).

Legacy log compatibility

Token fields (prompt_tokens, response_tokens) were introduced in v0.12. Logs written by earlier versions lack these fields entirely. When absent, the aggregation treats them as 0 (via unwrap_or(0)) — the same pattern used for other numeric fields (elapsed_ms, total_prompt_chars, etc.). This means per-strategy total_tokens may under-report if the dataset includes pre-v0.12 sessions.

impl AppService

pub async fn migrate( &self, project_root: Option<String>, ) -> Result<String, String>

impl AppService

pub async fn pkg_install( &self, url: String, name: Option<String>, ) -> Result<String, String>

Install a package from a Git URL or local path (string-typed, public MCP API).

Classifies url via [classify_install_url] then delegates to AppService::pkg_install_typed. Callers that already hold a classified [InstallSource] (e.g. pkg_repair) should call the typed API directly to avoid re-classifying a stale string.

impl AppService

pub async fn pkg_list( &self, project_root: Option<String>, ) -> Result<String, String>

List installed packages with metadata, showing the full override chain.

When project_root is provided (or resolvable), project-local packages from alc.toml are prepended with scope: "project", merged with version/source info from alc.lock. Global packages carry scope: "global". If a project package and a global package share the same name, the project one is active: true and the global one active: false.

impl AppService

pub async fn pkg_remove( &self, name: &str, project_root: Option<String>, version: Option<String>, ) -> Result<String, String>

Remove a package declaration from alc.toml and alc.lock.

Requires an alc.toml to be found via project_root or ancestor walk. Physical files in ~/.algocline/packages/ are not deleted.

• name: package name to remove.
• project_root: optional explicit project root.
• version: optional version constraint (when specified, only removes the matching alc.lock entry; omit to remove any version).

impl AppService

pub async fn pkg_repair( &self, name: Option<String>, project_root: Option<String>, ) -> Result<String, String>

Heal broken packages by re-installing from installed.json source.

name — restrict to a single package; None repairs every broken pkg. project_root — used for project / variant pkg path checks. Falls back to ancestor walk from cwd.

Returns JSON with repaired, skipped, unrepairable, failed arrays (each entry has name + per-bucket fields). Repair is best-effort: the per-pkg result is reported regardless of outcome.

impl AppService

pub async fn pkg_link( &self, path: String, name: Option<String>, force: Option<bool>, scope: Option<String>, project_root: Option<String>, ) -> Result<String, String>

Link a local directory as a package.

• scope = None | Some("global"): create a symlink in ~/.algocline/packages/{name}. Unix-only (symlink).
• scope = Some("variant"): record the path in alc.local.toml at the project root. Works on all platforms (no symlink).
• Any other scope value → Err.

force is only meaningful in global scope (overwrite real dir). project_root is only consulted in variant scope.

impl AppService

pub async fn pkg_unlink(&self, name: String) -> Result<String, String>

Remove a symlinked package from the global cache.

• If ~/.algocline/packages/{name} is a symlink: removes it.
• If it is a real directory: returns an error directing to pkg_remove.
• If it does not exist: returns an error.

impl AppService

pub async fn run( &self, code: Option<String>, code_file: Option<String>, ctx: Option<Value>, project_root: Option<String>, ) -> Result<String, String>

Execute Lua code with optional JSON context.

project_root — optional absolute path to the project root containing alc.lock. Falls back to ALC_PROJECT_ROOT env or ancestor walk.

pub async fn advice( &self, strategy: &str, task: Option<String>, opts: Option<Value>, project_root: Option<String>, ) -> Result<String, String>

Apply a built-in strategy to a task.

If the requested package is not installed, automatically installs the bundled package collection from GitHub before executing.

project_root — optional absolute path to the project root containing alc.lock. Falls back to ALC_PROJECT_ROOT env or ancestor walk.

pub async fn continue_batch( &self, session_id: &str, responses: Vec<QueryResponse>, ) -> Result<String, String>

Continue a paused execution — batch feed.

pub async fn continue_single( &self, session_id: &str, response: String, query_id: Option<&str>, usage: Option<TokenUsage>, ) -> Result<String, String>

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

impl AppService

pub fn scenario_list(&self) -> Result<String, String>

List available scenarios in ~/.algocline/scenarios/.

Per-entry I/O errors are collected in "failures" rather than aborting.

pub fn scenario_show(&self, name: &str) -> Result<String, String>

Show the content of a named scenario.

pub async fn scenario_install(&self, url: String) -> Result<String, String>

Install scenarios from a Git URL or local path into ~/.algocline/scenarios/.

Expects the source to contain .lua files (at root or in a scenarios/ subdirectory).

impl AppService

pub async fn status(&self, session_id: Option<&str>) -> Result<String, String>

Snapshot of all active sessions for external observation.

Returns JSON with session status, metrics, progress, and strategy name. Only includes sessions currently held in the registry (paused, awaiting host LLM responses). Completed sessions are not listed here — use alc_log_view for historical data.

impl AppService

pub async fn update( &self, project_root: Option<String>, ) -> Result<String, String>

impl AppService

pub fn new( executor: Arc<Executor>, log_config: AppConfig, search_paths: Vec<SearchPath>, ) -> Self

Trait Implementations

impl Clone for AppService

fn clone(&self) -> AppService

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl EngineApi for AppService

Delegates each EngineApi method to the corresponding AppService inherent method via fully-qualified syntax (AppService::method(self, …)).

This avoids ambiguity between the trait method and the inherent method of the same name, preventing accidental infinite recursion if the inherent method is ever removed or renamed.

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>, ) -> 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.

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.

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).

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/.

fn pkg_list<'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,

List installed packages with metadata.

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_remove<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, project_root: Option<String>, version: 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 declaration from alc.toml and alc.lock.

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 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.

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.

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.

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.

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.

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.

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.

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.

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<usize>, ) -> 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.

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.