feat: add main features

Agents for developpement added + frontend add + backend added. Git viewer created + agent and template creator + layout and project creator

crates/application/src/agent/lifecycle.rs

@@ -0,0 +1,538 @@
+//! Agent lifecycle use cases (ARCHITECTURE §6, L6).
+//!
+//! These own the *project-agent* side (distinct from the profile side in
+//! [`super::usecases`]): creating agents and their `.md` contexts under
+//! `.ideai/`, listing/reading/updating them, and — the centrepiece —
+//! [`LaunchAgent`], which resolves the agent's profile + context, applies the
+//! profile's context-injection strategy, opens a PTY cell at the right `cwd` and
+//! spawns the CLI.
+//!
+//! Every use case talks **only to ports** ([`AgentContextStore`], [`ProfileStore`],
+//! [`AgentRuntime`], [`PtyPort`], [`FileSystem`], [`EventBus`]); none knows about
+//! a concrete adapter or Tauri.
+
+use std::sync::Arc;
+
+use domain::ports::{
+    AgentContextStore, AgentRuntime, ContextInjectionPlan, EventBus, FileSystem, PreparedContext,
+    ProfileStore, PtyPort, RemotePath, SpawnSpec,
+};
+use domain::{
+    Agent, AgentId, AgentManifest, AgentOrigin, DomainEvent, ManifestEntry, MarkdownDoc, NodeId,
+    Project, ProfileId, ProjectPath, PtySize, SessionKind, SessionStatus, TerminalSession,
+};
+
+use crate::error::AppError;
+use crate::terminal::TerminalSessions;
+
+/// Directory (relative to `.ideai/`) under which agent contexts are written.
+const AGENTS_SUBDIR: &str = "agents";
+
+// ---------------------------------------------------------------------------
+// CreateAgentFromScratch
+// ---------------------------------------------------------------------------
+
+/// Input for [`CreateAgentFromScratch::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CreateAgentInput {
+    /// The project that owns the agent.
+    pub project: Project,
+    /// Display name of the agent.
+    pub name: String,
+    /// Runtime profile the agent launches with.
+    pub profile_id: ProfileId,
+    /// Initial `.md` content (empty when `None`).
+    pub initial_content: Option<String>,
+}
+
+/// Output of [`CreateAgentFromScratch::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CreateAgentOutput {
+    /// The freshly-created agent.
+    pub agent: Agent,
+}
+
+/// Creates a project agent from scratch: mints an id, derives a unique `.md`
+/// path, records the manifest entry, then writes the (possibly empty) context.
+pub struct CreateAgentFromScratch {
+    contexts: Arc<dyn AgentContextStore>,
+    ids: Arc<dyn domain::ports::IdGenerator>,
+    events: Arc<dyn EventBus>,
+}
+
+impl CreateAgentFromScratch {
+    /// Builds the use case from its injected ports.
+    #[must_use]
+    pub fn new(
+        contexts: Arc<dyn AgentContextStore>,
+        ids: Arc<dyn domain::ports::IdGenerator>,
+        events: Arc<dyn EventBus>,
+    ) -> Self {
+        Self {
+            contexts,
+            ids,
+            events,
+        }
+    }
+
+    /// Executes creation.
+    ///
+    /// Ordering matters: the manifest entry is persisted **before** the context
+    /// is written, because [`AgentContextStore::write_context`] resolves the
+    /// on-disk path from the manifest.
+    ///
+    /// # Errors
+    /// - [`AppError::Invalid`] if the name is empty or the manifest would become
+    ///   inconsistent,
+    /// - [`AppError::Store`] on persistence failure.
+    pub async fn execute(&self, input: CreateAgentInput) -> Result<CreateAgentOutput, AppError> {
+        let manifest = self.contexts.load_manifest(&input.project).await?;
+
+        let id = AgentId::from_uuid(self.ids.new_uuid());
+        let md_path = unique_md_path(&input.name, &manifest);
+
+        let agent = Agent::new(
+            id,
+            input.name,
+            md_path,
+            input.profile_id,
+            AgentOrigin::Scratch,
+            false,
+        )
+        .map_err(|e| AppError::Invalid(e.to_string()))?;
+
+        // Append the entry and re-validate the whole manifest (unique md_paths).
+        let mut entries = manifest.entries;
+        entries.push(ManifestEntry::from_agent(&agent));
+        let manifest = AgentManifest::new(manifest.version, entries)
+            .map_err(|e| AppError::Invalid(e.to_string()))?;
+        self.contexts.save_manifest(&input.project, &manifest).await?;
+
+        // Now the path resolves: write the initial context.
+        let md = MarkdownDoc::new(input.initial_content.unwrap_or_default());
+        self.contexts
+            .write_context(&input.project, &agent.id, &md)
+            .await?;
+
+        self.events.publish(DomainEvent::LayoutChanged {
+            project_id: input.project.id,
+        });
+
+        Ok(CreateAgentOutput { agent })
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ListAgents
+// ---------------------------------------------------------------------------
+
+/// Input for [`ListAgents::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ListAgentsInput {
+    /// The project whose agents to list.
+    pub project: Project,
+}
+
+/// Output of [`ListAgents::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ListAgentsOutput {
+    /// The project's agents (reconstructed from the manifest).
+    pub agents: Vec<Agent>,
+}
+
+/// Lists a project's agents by reconstructing them from the manifest entries.
+pub struct ListAgents {
+    contexts: Arc<dyn AgentContextStore>,
+}
+
+impl ListAgents {
+    /// Builds the use case from the [`AgentContextStore`] port.
+    #[must_use]
+    pub fn new(contexts: Arc<dyn AgentContextStore>) -> Self {
+        Self { contexts }
+    }
+
+    /// Loads the manifest and folds each entry back into an [`Agent`].
+    ///
+    /// # Errors
+    /// - [`AppError::Store`] on persistence failure,
+    /// - [`AppError::Invalid`] if a persisted entry violates an agent invariant.
+    pub async fn execute(&self, input: ListAgentsInput) -> Result<ListAgentsOutput, AppError> {
+        let manifest = self.contexts.load_manifest(&input.project).await?;
+        let agents = manifest
+            .entries
+            .iter()
+            .map(|e| e.to_agent().map_err(|err| AppError::Invalid(err.to_string())))
+            .collect::<Result<Vec<_>, _>>()?;
+        Ok(ListAgentsOutput { agents })
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ReadAgentContext / UpdateAgentContext
+// ---------------------------------------------------------------------------
+
+/// Input for [`ReadAgentContext::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReadAgentContextInput {
+    /// The owning project.
+    pub project: Project,
+    /// The agent whose `.md` to read.
+    pub agent_id: AgentId,
+}
+
+/// Output of [`ReadAgentContext::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReadAgentContextOutput {
+    /// The agent's Markdown context.
+    pub content: MarkdownDoc,
+}
+
+/// Reads an agent's `.md` context.
+pub struct ReadAgentContext {
+    contexts: Arc<dyn AgentContextStore>,
+}
+
+impl ReadAgentContext {
+    /// Builds the use case.
+    #[must_use]
+    pub fn new(contexts: Arc<dyn AgentContextStore>) -> Self {
+        Self { contexts }
+    }
+
+    /// Reads the context.
+    ///
+    /// # Errors
+    /// - [`AppError::NotFound`] if the agent (or its `.md`) is unknown,
+    /// - [`AppError::Store`] on persistence failure.
+    pub async fn execute(
+        &self,
+        input: ReadAgentContextInput,
+    ) -> Result<ReadAgentContextOutput, AppError> {
+        let content = self
+            .contexts
+            .read_context(&input.project, &input.agent_id)
+            .await?;
+        Ok(ReadAgentContextOutput { content })
+    }
+}
+
+/// Input for [`UpdateAgentContext::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateAgentContextInput {
+    /// The owning project.
+    pub project: Project,
+    /// The agent whose `.md` to overwrite.
+    pub agent_id: AgentId,
+    /// New Markdown content.
+    pub content: String,
+}
+
+/// Overwrites an agent's `.md` context.
+pub struct UpdateAgentContext {
+    contexts: Arc<dyn AgentContextStore>,
+}
+
+impl UpdateAgentContext {
+    /// Builds the use case.
+    #[must_use]
+    pub fn new(contexts: Arc<dyn AgentContextStore>) -> Self {
+        Self { contexts }
+    }
+
+    /// Writes the new context.
+    ///
+    /// # Errors
+    /// - [`AppError::NotFound`] if the agent is unknown,
+    /// - [`AppError::Store`] on persistence failure.
+    pub async fn execute(&self, input: UpdateAgentContextInput) -> Result<(), AppError> {
+        let md = MarkdownDoc::new(input.content);
+        self.contexts
+            .write_context(&input.project, &input.agent_id, &md)
+            .await?;
+        Ok(())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// DeleteAgent
+// ---------------------------------------------------------------------------
+
+/// Input for [`DeleteAgent::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeleteAgentInput {
+    /// The owning project.
+    pub project: Project,
+    /// The agent to remove.
+    pub agent_id: AgentId,
+}
+
+/// Removes an agent from the project manifest.
+///
+/// The orphaned `.md` file is left on disk: the [`FileSystem`] port exposes no
+/// delete, and keeping the file is the safe default (the user may want to recover
+/// the context). Re-creating an agent with the same name reuses a fresh path.
+pub struct DeleteAgent {
+    contexts: Arc<dyn AgentContextStore>,
+    events: Arc<dyn EventBus>,
+}
+
+impl DeleteAgent {
+    /// Builds the use case.
+    #[must_use]
+    pub fn new(contexts: Arc<dyn AgentContextStore>, events: Arc<dyn EventBus>) -> Self {
+        Self { contexts, events }
+    }
+
+    /// Drops the manifest entry for the agent.
+    ///
+    /// # Errors
+    /// - [`AppError::NotFound`] if the agent is not in the manifest,
+    /// - [`AppError::Store`] on persistence failure.
+    pub async fn execute(&self, input: DeleteAgentInput) -> Result<(), AppError> {
+        let manifest = self.contexts.load_manifest(&input.project).await?;
+        let before = manifest.entries.len();
+        let entries: Vec<ManifestEntry> = manifest
+            .entries
+            .into_iter()
+            .filter(|e| e.agent_id != input.agent_id)
+            .collect();
+        if entries.len() == before {
+            return Err(AppError::NotFound(format!("agent {}", input.agent_id)));
+        }
+        let manifest = AgentManifest::new(manifest.version, entries)
+            .map_err(|e| AppError::Invalid(e.to_string()))?;
+        self.contexts.save_manifest(&input.project, &manifest).await?;
+        self.events.publish(DomainEvent::LayoutChanged {
+            project_id: input.project.id,
+        });
+        Ok(())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// LaunchAgent
+// ---------------------------------------------------------------------------
+
+/// Input for [`LaunchAgent::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaunchAgentInput {
+    /// The owning project.
+    pub project: Project,
+    /// The agent to launch.
+    pub agent_id: AgentId,
+    /// Initial terminal height in rows.
+    pub rows: u16,
+    /// Initial terminal width in columns.
+    pub cols: u16,
+    /// The layout leaf hosting the session (a fresh node when `None`).
+    pub node_id: Option<NodeId>,
+}
+
+/// Output of [`LaunchAgent::execute`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaunchAgentOutput {
+    /// The created agent terminal session.
+    pub session: TerminalSession,
+}
+
+/// Launches an agent: resolve profile + context, prepare the invocation, apply
+/// the context-injection plan, open a PTY at the resolved `cwd`, spawn the CLI.
+///
+/// This is the orchestrating use case of L6 and therefore consumes several ports
+/// — each only for the slice it needs (Interface Segregation): the context store
+/// (agent `.md` + manifest), the profile store (resolve the runtime), the runtime
+/// (build the [`SpawnSpec`]), the filesystem (materialise a `conventionFile`
+/// context), and the PTY (spawn + optional stdin injection).
+pub struct LaunchAgent {
+    contexts: Arc<dyn AgentContextStore>,
+    profiles: Arc<dyn ProfileStore>,
+    runtime: Arc<dyn AgentRuntime>,
+    fs: Arc<dyn FileSystem>,
+    pty: Arc<dyn PtyPort>,
+    sessions: Arc<TerminalSessions>,
+    events: Arc<dyn EventBus>,
+}
+
+impl LaunchAgent {
+    /// Builds the use case from its injected ports.
+    #[must_use]
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        contexts: Arc<dyn AgentContextStore>,
+        profiles: Arc<dyn ProfileStore>,
+        runtime: Arc<dyn AgentRuntime>,
+        fs: Arc<dyn FileSystem>,
+        pty: Arc<dyn PtyPort>,
+        sessions: Arc<TerminalSessions>,
+        events: Arc<dyn EventBus>,
+    ) -> Self {
+        Self {
+            contexts,
+            profiles,
+            runtime,
+            fs,
+            pty,
+            sessions,
+            events,
+        }
+    }
+
+    /// Executes the launch.
+    ///
+    /// Step order is contractually significant (and unit-tested): resolve the
+    /// agent + context, **`prepare_invocation`**, **apply the injection plan**
+    /// (write a `conventionFile` / set an env var), then **`pty.spawn`** at the
+    /// resolved `cwd`, and finally pipe the context on stdin for the `Stdin`
+    /// strategy.
+    ///
+    /// # Errors
+    /// - [`AppError::NotFound`] if the agent or its profile is unknown,
+    /// - [`AppError::Invalid`] for a zero-sized terminal,
+    /// - [`AppError::Store`] / [`AppError::FileSystem`] / [`AppError::Process`] on
+    ///   the respective port failures.
+    pub async fn execute(&self, input: LaunchAgentInput) -> Result<LaunchAgentOutput, AppError> {
+        let size =
+            PtySize::new(input.rows, input.cols).map_err(|e| AppError::Invalid(e.to_string()))?;
+
+        // 1. Resolve the agent from the manifest (name + profile + md_path).
+        let manifest = self.contexts.load_manifest(&input.project).await?;
+        let entry = manifest
+            .entries
+            .iter()
+            .find(|e| e.agent_id == input.agent_id)
+            .ok_or_else(|| AppError::NotFound(format!("agent {}", input.agent_id)))?;
+        let agent = entry
+            .to_agent()
+            .map_err(|e| AppError::Invalid(e.to_string()))?;
+
+        // 2. Read its context and resolve its profile.
+        let content = self
+            .contexts
+            .read_context(&input.project, &agent.id)
+            .await?;
+        let profile = self
+            .profiles
+            .list()
+            .await?
+            .into_iter()
+            .find(|p| p.id == agent.profile_id)
+            .ok_or_else(|| {
+                AppError::NotFound(format!("profile {} for agent", agent.profile_id))
+            })?;
+
+        // 3. Prepare the invocation (pure): command + args + injection plan + cwd.
+        let prepared = PreparedContext {
+            content: content.clone(),
+            relative_path: agent.context_path.clone(),
+        };
+        let mut spec = self
+            .runtime
+            .prepare_invocation(&profile, &prepared, &input.project.root)?;
+
+        // 4. Apply the injection plan side effects *before* spawning.
+        self.apply_injection(&input.project, &agent.context_path, &content, &mut spec)
+            .await?;
+
+        // 5. Spawn the PTY at the resolved cwd; adopt its session id everywhere.
+        let handle = self.pty.spawn(spec.clone(), size).await?;
+        let session_id = handle.session_id;
+
+        // 6. For the Stdin strategy, pipe the context once the PTY is live.
+        if matches!(spec.context_plan, Some(ContextInjectionPlan::Stdin)) {
+            self.pty.write(&handle, content.as_str().as_bytes())?;
+        }
+
+        let node_id = input.node_id.unwrap_or_else(NodeId::new_random);
+        let mut session = TerminalSession::starting(
+            session_id,
+            node_id,
+            spec.cwd.clone(),
+            SessionKind::Agent {
+                agent_id: agent.id,
+            },
+            size,
+        );
+        session.status = SessionStatus::Running;
+        self.sessions.insert(handle, session.clone());
+
+        self.events.publish(DomainEvent::AgentLaunched {
+            agent_id: agent.id,
+            session_id,
+        });
+
+        Ok(LaunchAgentOutput { session })
+    }
+
+    /// Applies the context-injection plan that must happen *before* spawn:
+    /// materialising a `conventionFile` context (write the `.md` to `<cwd>/target`)
+    /// or attaching the on-disk context path to an environment variable. `Args` is
+    /// already folded into the spec by the runtime; `Stdin` is handled post-spawn.
+    async fn apply_injection(
+        &self,
+        project: &Project,
+        context_rel_path: &str,
+        content: &MarkdownDoc,
+        spec: &mut SpawnSpec,
+    ) -> Result<(), AppError> {
+        match spec.context_plan.clone() {
+            Some(ContextInjectionPlan::File { target }) => {
+                // conventionFile spike (ARCHITECTURE §13.6): copy the context to the
+                // conventional file (e.g. CLAUDE.md), overwriting any existing one.
+                // A copy (not a symlink) is the portable choice — Windows symlinks
+                // need privileges and SFTP/WSL symlink semantics differ.
+                let path = RemotePath::new(join(&spec.cwd, &target));
+                self.fs.write(&path, content.as_str().as_bytes()).await?;
+            }
+            Some(ContextInjectionPlan::Env { var }) => {
+                // Hand the CLI the absolute path of the agent's `.md` (which lives at
+                // `<root>/.ideai/<context_rel_path>`) via the environment variable.
+                let abspath = join(&project.root, &format!(".ideai/{context_rel_path}"));
+                spec.env.push((var, abspath));
+            }
+            // Args were folded into spec.args by prepare_invocation; Stdin is
+            // applied after the PTY is live.
+            Some(ContextInjectionPlan::Args { .. }) | Some(ContextInjectionPlan::Stdin) | None => {}
+        }
+        Ok(())
+    }
+}
+
+/// Builds an absolute path string by joining a [`ProjectPath`] with a relative
+/// segment using a POSIX separator.
+fn join(base: &ProjectPath, rel: &str) -> String {
+    let b = base.as_str().trim_end_matches(['/', '\\']);
+    format!("{b}/{rel}")
+}
+
+/// Derives a unique, filesystem-safe `md_path` (`agents/<slug>.md`) for a new
+/// agent, disambiguating against the manifest's existing paths with a numeric
+/// suffix when needed. Shared with the template-driven agent creation (L7).
+pub(crate) fn unique_md_path(name: &str, manifest: &AgentManifest) -> String {
+    let slug = slugify(name);
+    let base = if slug.is_empty() { "agent".to_owned() } else { slug };
+    let mut candidate = format!("{AGENTS_SUBDIR}/{base}.md");
+    let mut n = 2;
+    while manifest.entries.iter().any(|e| e.md_path == candidate) {
+        candidate = format!("{AGENTS_SUBDIR}/{base}-{n}.md");
+        n += 1;
+    }
+    candidate
+}
+
+/// Lowercases and slugifies a display name into a safe file stem
+/// (`[a-z0-9-]`), collapsing runs of separators.
+fn slugify(name: &str) -> String {
+    let mut out = String::with_capacity(name.len());
+    let mut prev_dash = false;
+    for ch in name.trim().chars() {
+        if ch.is_ascii_alphanumeric() {
+            out.push(ch.to_ascii_lowercase());
+            prev_dash = false;
+        } else if !prev_dash {
+            out.push('-');
+            prev_dash = true;
+        }
+    }
+    out.trim_matches('-').to_owned()
+}