storkit/server/src/io/onboarding.rs

use std::path::Path;

/// Unique marker found in the scaffold template for `00_CONTEXT.md`.
/// If the project's context file contains this phrase, it is still the
/// default scaffold content and needs to be replaced.
const TEMPLATE_MARKER_CONTEXT: &str = "Agentic AI Code Assistant";

/// Unique marker found in the scaffold template for `STACK.md`.
const TEMPLATE_MARKER_STACK: &str = "Agentic Code Assistant";

/// Marker found in the default `script/test` scaffold output.
const TEMPLATE_MARKER_SCRIPT: &str = "No tests configured";

/// Summary of what parts of a project still need onboarding.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OnboardingStatus {
    /// True when the project context spec needs to be populated.
    pub needs_context: bool,
    /// True when the tech stack spec needs to be populated.
    pub needs_stack: bool,
    /// True when `script/test` still contains the scaffold placeholder.
    pub needs_test_script: bool,
    /// True when `.story_kit/project.toml` is missing or has no
    /// `[[component]]` entries.
    pub needs_project_toml: bool,
}

impl OnboardingStatus {
    /// Returns `true` when any onboarding step is still needed.
    pub fn needs_onboarding(&self) -> bool {
        self.needs_context || self.needs_stack
    }
}

/// Inspect the project at `project_root` and determine which onboarding
/// steps are still required.
pub fn check_onboarding_status(project_root: &Path) -> OnboardingStatus {
    let story_kit = project_root.join(".story_kit");

    OnboardingStatus {
        needs_context: is_template_or_missing(
            &story_kit.join("specs").join("00_CONTEXT.md"),
            TEMPLATE_MARKER_CONTEXT,
        ),
        needs_stack: is_template_or_missing(
            &story_kit.join("specs").join("tech").join("STACK.md"),
            TEMPLATE_MARKER_STACK,
        ),
        needs_test_script: is_template_or_missing(
            &project_root.join("script").join("test"),
            TEMPLATE_MARKER_SCRIPT,
        ),
        needs_project_toml: needs_project_toml(&story_kit),
    }
}

/// Returns `true` when the file is missing, empty, or contains the
/// given scaffold marker string.
fn is_template_or_missing(path: &Path, marker: &str) -> bool {
    match std::fs::read_to_string(path) {
        Ok(content) => content.trim().is_empty() || content.contains(marker),
        Err(_) => true,
    }
}

/// Returns `true` when `project.toml` is missing or has no
/// `[[component]]` entries.
fn needs_project_toml(story_kit: &Path) -> bool {
    let toml_path = story_kit.join("project.toml");
    match std::fs::read_to_string(toml_path) {
        Ok(content) => !content.contains("[[component]]"),
        Err(_) => true,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs;
    use tempfile::TempDir;

    fn setup_project(dir: &TempDir) -> std::path::PathBuf {
        let root = dir.path().to_path_buf();
        let sk = root.join(".story_kit");
        fs::create_dir_all(sk.join("specs").join("tech")).unwrap();
        fs::create_dir_all(root.join("script")).unwrap();
        root
    }

    // ── needs_onboarding ──────────────────────────────────────────

    #[test]
    fn needs_onboarding_true_when_no_files_exist() {
        let dir = TempDir::new().unwrap();
        let root = dir.path().to_path_buf();
        let status = check_onboarding_status(&root);
        assert!(status.needs_onboarding());
        assert!(status.needs_context);
        assert!(status.needs_stack);
        assert!(status.needs_test_script);
        assert!(status.needs_project_toml);
    }

    #[test]
    fn needs_onboarding_true_when_specs_contain_scaffold_markers() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        // Write scaffold template content
        fs::write(
            root.join(".story_kit/specs/00_CONTEXT.md"),
            "# Project Context\nTo build a standalone Agentic AI Code Assistant...",
        )
        .unwrap();
        fs::write(
            root.join(".story_kit/specs/tech/STACK.md"),
            "# Tech Stack\nThis is an Agentic Code Assistant binary...",
        )
        .unwrap();

        let status = check_onboarding_status(&root);
        assert!(status.needs_context);
        assert!(status.needs_stack);
        assert!(status.needs_onboarding());
    }

    #[test]
    fn needs_onboarding_false_when_specs_have_custom_content() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        fs::write(
            root.join(".story_kit/specs/00_CONTEXT.md"),
            "# My Project\n\nThis is an e-commerce platform for selling widgets.",
        )
        .unwrap();
        fs::write(
            root.join(".story_kit/specs/tech/STACK.md"),
            "# Tech Stack\n\n## Backend: Python + FastAPI\n## Frontend: React + TypeScript",
        )
        .unwrap();

        let status = check_onboarding_status(&root);
        assert!(!status.needs_context);
        assert!(!status.needs_stack);
        assert!(!status.needs_onboarding());
    }

    #[test]
    fn needs_onboarding_true_when_specs_are_empty() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        fs::write(root.join(".story_kit/specs/00_CONTEXT.md"), "  \n").unwrap();
        fs::write(root.join(".story_kit/specs/tech/STACK.md"), "").unwrap();

        let status = check_onboarding_status(&root);
        assert!(status.needs_context);
        assert!(status.needs_stack);
    }

    // ── needs_test_script ─────────────────────────────────────────

    #[test]
    fn needs_test_script_true_when_placeholder() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        fs::write(
            root.join("script/test"),
            "#!/usr/bin/env bash\nset -euo pipefail\necho \"No tests configured\"\n",
        )
        .unwrap();

        let status = check_onboarding_status(&root);
        assert!(status.needs_test_script);
    }

    #[test]
    fn needs_test_script_false_when_customised() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        fs::write(
            root.join("script/test"),
            "#!/usr/bin/env bash\nset -euo pipefail\ncargo test\n",
        )
        .unwrap();

        let status = check_onboarding_status(&root);
        assert!(!status.needs_test_script);
    }

    // ── needs_project_toml ────────────────────────────────────────

    #[test]
    fn needs_project_toml_true_when_missing() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        let status = check_onboarding_status(&root);
        assert!(status.needs_project_toml);
    }

    #[test]
    fn needs_project_toml_true_when_no_components() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        fs::write(
            root.join(".story_kit/project.toml"),
            "# empty config\n",
        )
        .unwrap();

        let status = check_onboarding_status(&root);
        assert!(status.needs_project_toml);
    }

    #[test]
    fn needs_project_toml_false_when_has_components() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        fs::write(
            root.join(".story_kit/project.toml"),
            "[[component]]\nname = \"app\"\npath = \".\"\nsetup = [\"cargo check\"]\n",
        )
        .unwrap();

        let status = check_onboarding_status(&root);
        assert!(!status.needs_project_toml);
    }

    // ── partial onboarding ────────────────────────────────────────

    #[test]
    fn needs_onboarding_true_when_only_context_is_template() {
        let dir = TempDir::new().unwrap();
        let root = setup_project(&dir);

        // Context is still template
        fs::write(
            root.join(".story_kit/specs/00_CONTEXT.md"),
            "Agentic AI Code Assistant placeholder",
        )
        .unwrap();
        // Stack is customised
        fs::write(
            root.join(".story_kit/specs/tech/STACK.md"),
            "# My Stack\nRuby on Rails + PostgreSQL",
        )
        .unwrap();

        let status = check_onboarding_status(&root);
        assert!(status.needs_context);
        assert!(!status.needs_stack);
        assert!(status.needs_onboarding());
    }
}