reallink-cli 0.1.12 → 0.1.13

package/README.md

@@ -53,6 +53,7 @@ reallink token create --name "ci-token" --scope trace:read --scope trace:write
 reallink token revoke --token-id tok_xxx
 
 reallink file list --project-id prj_xxx
+reallink file tree --project-id prj_xxx
 reallink file get --asset-id ast_xxx
 reallink file stat --asset-id ast_xxx
 reallink file download --asset-id ast_xxx --output ./downloads/report.json
@@ -60,15 +61,25 @@ reallink file download --asset-id ast_xxx --output ./downloads/report.json --res
 reallink file upload --project-id prj_xxx --source ./local/report.json --path reports/daily
 reallink file mkdir --project-id prj_xxx --path reports/archive
 reallink file move --asset-id ast_xxx --file-name reports/archive/report.json
+reallink file move-folder --project-id prj_xxx --source-path reports/archive --target-path reports/2026
 reallink file remove --asset-id ast_xxx
 
+reallink logs status
+reallink logs consent --enable
+reallink logs tail --lines 120
+reallink logs upload --project-id prj_xxx --dry-run
+reallink logs upload --project-id prj_xxx --clear-on-success
+
 reallink tool list
 reallink tool register --manifest ./spec/tools/trace-placeholder.tool.jsonc
+reallink tool publish --tool-id trace.placeholder --channel ga --visibility public
 reallink tool enable --tool-id trace.placeholder --project-id prj_xxx
 reallink tool enable --tool-id trace.placeholder --user-id usr_xxx
 reallink tool run --tool-id trace.placeholder --project-id prj_xxx --input-file ./run-input.jsonc --idempotency-key run-001
 reallink tool runs --project-id prj_xxx
 reallink tool get-run --run-id trun_xxx
+reallink tool run-events --run-id trun_xxx --limit 200
+reallink tool run-events --run-id trun_xxx --stage-prefix workflow. --status succeeded
 
 reallink link unreal --project-id prj_xxx --uproject "D:/Games/MyGame/MyGame.uproject" --engine-root "D:/Epic/UE_5.4" --set-default
 reallink link list
@@ -100,9 +111,24 @@ reallink link plugin install --project-id prj_xxx --name RealLinkUnreal --url ht
 - Login stores a local session at:
   - Windows: `%APPDATA%\\reallink\\session.json`
   - Linux/macOS: `${XDG_CONFIG_HOME:-~/.config}/reallink/session.json`
+- Access token TTL: 15 minutes (auto-refreshed by CLI on 401).
+- Refresh/session TTL: 30 days.
 - You only need to log in again when the saved session is invalid/expired or you explicitly run `reallink logout`.
 - `reallink logout` revokes the current server session (`/auth/logout`) and clears the local session file.
 
+## CLI Logs & Crash Reports
+
+- Local logs are written under:
+  - Windows: `%APPDATA%\\reallink\\logs\\`
+  - Linux/macOS: `${XDG_CONFIG_HOME:-~/.config}/reallink/logs/`
+- Runtime log file: `runtime.jsonl`
+- Crash reports: `crash/crash-<epoch>.json`
+- Uploading logs requires explicit consent:
+  - `reallink logs consent --enable`
+- Upload destination path in project storage:
+  - `.reallink/logs/cli/runtime/*`
+  - `.reallink/logs/cli/crash/*`
+
 ## Unreal Link Architecture
 
 `reallink link ...` provides a Vercel-style "link local project to remote project" workflow for local Unreal development.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reallink-cli",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Rust-based CLI for Reallink auth and API operations",
   "bin": {
     "reallink": "bin/reallink.cjs"

package/rust/Cargo.lock

@@ -993,7 +993,7 @@ dependencies = [
 
 [[package]]
 name = "reallink-cli"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "anyhow",
  "clap",

package/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "reallink-cli"
-version = "0.1.12"
+version = "0.1.13"
 edition = "2021"
 description = "CLI for Reallink auth and token workflows"
 license = "MIT"

package/rust/src/generated/contract.rs

@@ -2,7 +2,7 @@
 // Do not edit by hand. Update packages/shared/src/api-contract.ts and re-run codegen.
 #![allow(dead_code)]
 
-pub const API_CONTRACT_VERSION: &str = "2026.03.0";
+pub const API_CONTRACT_VERSION: &str = "2026.03.1";
 pub const API_TOKEN_SCOPES: &[&str] = &[
     "core:read",
     "core:write",

package/rust/src/logs.rs

@@ -0,0 +1,277 @@
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::VecDeque;
+use std::fs::{self, OpenOptions};
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+const LOGS_DIR: &str = "logs";
+const CRASH_DIR: &str = "crash";
+const CONSENT_FILE: &str = "consent.json";
+const RUNTIME_LOG_FILE: &str = "runtime.jsonl";
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LogConsentConfig {
+    pub upload_enabled: bool,
+    pub asked_at_epoch_ms: Option<u128>,
+    pub updated_at_epoch_ms: u128,
+}
+
+impl Default for LogConsentConfig {
+    fn default() -> Self {
+        Self {
+            upload_enabled: false,
+            asked_at_epoch_ms: None,
+            updated_at_epoch_ms: now_epoch_ms(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeLogEvent {
+    pub ts_epoch_ms: u128,
+    pub level: String,
+    pub command: String,
+    pub message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub duration_ms: Option<u128>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub exit_code: Option<i32>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CrashReport {
+    pub ts_epoch_ms: u128,
+    pub command: String,
+    pub message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub detail: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LogUploadCandidate {
+    pub local_path: PathBuf,
+    pub remote_path: String,
+    pub content_type: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LogStatus {
+    pub logs_root: String,
+    pub runtime_log_path: String,
+    pub crash_dir: String,
+    pub consent_file_path: String,
+    pub consent: LogConsentConfig,
+    pub runtime_exists: bool,
+    pub crash_report_count: usize,
+}
+
+fn now_epoch_ms() -> u128 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_else(|_| Duration::from_secs(0))
+        .as_millis()
+}
+
+fn write_atomic(path: &Path, payload: &[u8]) -> Result<()> {
+    let temp_path = path.with_extension(format!("tmp.{}", now_epoch_ms()));
+    fs::write(&temp_path, payload)
+        .with_context(|| format!("Failed to write temporary file {}", temp_path.display()))?;
+    if path.exists() {
+        fs::remove_file(path).with_context(|| format!("Failed to replace {}", path.display()))?;
+    }
+    fs::rename(&temp_path, path).with_context(|| {
+        format!(
+            "Failed to move temporary file {} to {}",
+            temp_path.display(),
+            path.display()
+        )
+    })?;
+    Ok(())
+}
+
+fn logs_root(state_root: &Path) -> PathBuf {
+    state_root.join(LOGS_DIR)
+}
+
+fn crash_dir(state_root: &Path) -> PathBuf {
+    logs_root(state_root).join(CRASH_DIR)
+}
+
+fn consent_path(state_root: &Path) -> PathBuf {
+    logs_root(state_root).join(CONSENT_FILE)
+}
+
+fn runtime_log_path(state_root: &Path) -> PathBuf {
+    logs_root(state_root).join(RUNTIME_LOG_FILE)
+}
+
+fn ensure_logs_dirs(state_root: &Path) -> Result<()> {
+    fs::create_dir_all(logs_root(state_root))
+        .with_context(|| format!("Failed to create {}", logs_root(state_root).display()))?;
+    fs::create_dir_all(crash_dir(state_root))
+        .with_context(|| format!("Failed to create {}", crash_dir(state_root).display()))?;
+    Ok(())
+}
+
+pub fn load_consent(state_root: &Path) -> Result<LogConsentConfig> {
+    let path = consent_path(state_root);
+    if !path.exists() {
+        return Ok(LogConsentConfig::default());
+    }
+    let raw =
+        fs::read(&path).with_context(|| format!("Failed to read consent file {}", path.display()))?;
+    let parsed: LogConsentConfig = serde_json::from_slice(&raw)
+        .with_context(|| format!("Invalid consent file {}", path.display()))?;
+    Ok(parsed)
+}
+
+pub fn set_upload_consent(state_root: &Path, enabled: bool) -> Result<LogConsentConfig> {
+    ensure_logs_dirs(state_root)?;
+    let mut current = load_consent(state_root)?;
+    let now = now_epoch_ms();
+    current.upload_enabled = enabled;
+    current.updated_at_epoch_ms = now;
+    if current.asked_at_epoch_ms.is_none() {
+        current.asked_at_epoch_ms = Some(now);
+    }
+    save_consent(state_root, &current)?;
+    Ok(current)
+}
+
+pub fn save_consent(state_root: &Path, config: &LogConsentConfig) -> Result<()> {
+    ensure_logs_dirs(state_root)?;
+    let path = consent_path(state_root);
+    let payload = serde_json::to_vec_pretty(config)?;
+    write_atomic(&path, &payload)?;
+    Ok(())
+}
+
+pub fn append_runtime_event(state_root: &Path, event: &RuntimeLogEvent) -> Result<()> {
+    ensure_logs_dirs(state_root)?;
+    let path = runtime_log_path(state_root);
+    let mut writer = OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(&path)
+        .with_context(|| format!("Failed to open runtime log {}", path.display()))?;
+    let line = serde_json::to_string(event)?;
+    writer
+        .write_all(format!("{}\n", line).as_bytes())
+        .with_context(|| format!("Failed to write runtime log {}", path.display()))?;
+    Ok(())
+}
+
+pub fn write_crash_report(state_root: &Path, report: &CrashReport) -> Result<PathBuf> {
+    ensure_logs_dirs(state_root)?;
+    let file_name = format!("crash-{}.json", report.ts_epoch_ms);
+    let path = crash_dir(state_root).join(file_name);
+    let payload = serde_json::to_vec_pretty(report)?;
+    write_atomic(&path, &payload)?;
+    Ok(path)
+}
+
+fn file_name_string(path: &Path) -> Option<String> {
+    path.file_name()
+        .and_then(|value| value.to_str())
+        .map(|value| value.to_string())
+}
+
+fn content_type_for_path(path: &Path) -> String {
+    match path.extension().and_then(|value| value.to_str()) {
+        Some("json") => "application/json".to_string(),
+        Some("jsonl") => "application/x-ndjson".to_string(),
+        Some("log") | Some("txt") => "text/plain".to_string(),
+        _ => "application/octet-stream".to_string(),
+    }
+}
+
+pub fn list_upload_candidates(
+    state_root: &Path,
+    include_runtime: bool,
+    include_crash: bool,
+) -> Result<Vec<LogUploadCandidate>> {
+    ensure_logs_dirs(state_root)?;
+    let mut output = Vec::new();
+
+    if include_runtime {
+        let runtime_path = runtime_log_path(state_root);
+        if runtime_path.exists() && runtime_path.is_file() {
+            if let Some(file_name) = file_name_string(&runtime_path) {
+                output.push(LogUploadCandidate {
+                    local_path: runtime_path.clone(),
+                    remote_path: format!(".reallink/logs/cli/runtime/{}", file_name),
+                    content_type: content_type_for_path(&runtime_path),
+                });
+            }
+        }
+    }
+
+    if include_crash {
+        let mut crash_files: Vec<PathBuf> = fs::read_dir(crash_dir(state_root))
+            .with_context(|| format!("Failed to read {}", crash_dir(state_root).display()))?
+            .filter_map(|entry| entry.ok().map(|item| item.path()))
+            .filter(|path| path.is_file())
+            .collect();
+        crash_files.sort();
+        for path in crash_files {
+            if let Some(file_name) = file_name_string(&path) {
+                output.push(LogUploadCandidate {
+                    local_path: path.clone(),
+                    remote_path: format!(".reallink/logs/cli/crash/{}", file_name),
+                    content_type: content_type_for_path(&path),
+                });
+            }
+        }
+    }
+
+    Ok(output)
+}
+
+pub fn read_runtime_tail(state_root: &Path, lines: usize) -> Result<Vec<String>> {
+    let path = runtime_log_path(state_root);
+    if !path.exists() {
+        return Ok(Vec::new());
+    }
+    let content = fs::read_to_string(&path)
+        .with_context(|| format!("Failed to read runtime log {}", path.display()))?;
+    if lines == 0 {
+        return Ok(Vec::new());
+    }
+    let mut deque = VecDeque::with_capacity(lines);
+    for line in content.lines() {
+        if deque.len() == lines {
+            deque.pop_front();
+        }
+        deque.push_back(line.to_string());
+    }
+    Ok(deque.into_iter().collect())
+}
+
+pub fn status(state_root: &Path) -> Result<LogStatus> {
+    ensure_logs_dirs(state_root)?;
+    let runtime_path = runtime_log_path(state_root);
+    let crash_directory = crash_dir(state_root);
+    let crash_count = fs::read_dir(&crash_directory)
+        .with_context(|| format!("Failed to read crash directory {}", crash_directory.display()))?
+        .filter_map(|entry| entry.ok())
+        .filter(|entry| entry.path().is_file())
+        .count();
+    let consent = load_consent(state_root)?;
+
+    Ok(LogStatus {
+        logs_root: logs_root(state_root).display().to_string(),
+        runtime_log_path: runtime_path.display().to_string(),
+        crash_dir: crash_directory.display().to_string(),
+        consent_file_path: consent_path(state_root).display().to_string(),
+        consent,
+        runtime_exists: runtime_path.exists(),
+        crash_report_count: crash_count,
+    })
+}