kanbrain_core/cli/

init.rs

//! `kb init`: makes the current folder a project. It gets its own `.brain/` with a card
//! (`project.md`: its name and what it's about), is registered in the central brain so the kanban app
//! shows it and can filter by it, and its coding agents are told how to use it, by a short section in
//! their instructions file (`CLAUDE.md`, `AGENTS.md`). Without that section an agent doesn't know the
//! brain exists until someone pastes it by hand.
//!
//! `kb deinit` undoes it, except for `.brain/` itself: its tasks, notes and decisions are the
//! repository's, often committed with it, so deleting them is left to the user.

use super::claude;
use crate::projects;
use crate::store::{self, PROJECT_DIR, Store};
use anyhow::{Context, Result, bail};
use std::fs;
use std::path::Path;

/// Instructions files agents read at the start of a session: Claude Code's, and the cross-agent one.
const AGENT_FILES: [&str; 2] = ["CLAUDE.md", "AGENTS.md"];
/// Created when the project has none of `AGENT_FILES`.
const DEFAULT_AGENT_FILE: &str = "CLAUDE.md";
/// Marks where the section starts and ends, so running `init` again updates it in place instead of
/// adding another, and everything around it is left alone.
const START: &str = "<!-- kanbrain:start -->";
/// See [`START`].
const END: &str = "<!-- kanbrain:end -->";

/// The section. Read at the start of every session, so it's short, yet the whole CLI an agent needs is
/// here. It has to win over the agent's own habits: Claude Code, for one, has a built-in to-do list,
/// and works through a plan without a word to the board unless told the board is watched live.
const SECTION: &str = "\
## Project memory: kanbrain

This project's tasks, to-dos, decisions and notes live in `.brain/`, managed only with `kb`, kanbrain's CLI.
The user follows them live on a kanban board: keep it showing what you're doing as you go, not at the end.

- Start of session: `kb context`, unless its output is already above (a session hook adds it).
- Work that changes the repository, or that the user should see, gets a task; questions and lookups don't. Find it
  (`search WORDS`) or create it (`add TITLE`), then `start ID` (`add --start TITLE` does both). \"Todos\", a plan or
  what's pending, in any language, are tasks here, one `add` each; your built-in to-do list isn't on the board, so
  keep it for steps within the task you've started. A task with real work gets a body, `add --body - TITLE`:
  **Goal** (what and why, a line or two) and **Done when** (what the user will check).
- While working: `comment ID TEXT` when a step is done, when you find a cause, and before you stop (one or two
  lines: what changed, what's next); `done ID` as soon as one is finished. Stopping before it is: `comment`, then
  `park ID`. Doing isn't limited for you: several of your tasks can run at once. Never park, finish or move a task
  you didn't start (the user's, or another session's).
- Splitting work between subagents: give each part that changes the repository its own task, and run the board
  yourself: `add --start` it before launching the subagent, then `comment` its result and `done` it. Subagents
  only do the work; lookups and research get no task. `kb` commands can run in parallel.
- Blocked on the user (a requirement, access, a choice that's theirs): `ask ID TEXT` parks the task with the
  question; don't guess. A choice you shouldn't make alone and weren't asked to (architecture, a dependency,
  storage, a public interface): `propose ID --body - TITLE`, Context / Options / Recommendation on stdin; it parks
  the task until the user accepts or rejects it. Then, unless the user said they're away, if your tool can run a
  command in the background and wake you when it exits, run `kb wait ID` (the task) that way and end your turn: it
  prints the answer, or that there's none yet (then stop, don't wait again). Otherwise go on with other work or
  stop; answers come first in `context`, under Answered: `show ID`, then pick the task up. If the user answers in
  the chat instead, `start` the task (that ends the wait). `accept`/`reject` a decision only when the user tells
  you to.
- Choosing between approaches within your task: `search` for earlier decisions (only accepted ones are in force),
  then `add --decision --link ID --body - TITLE` with Context / Decision / Consequences on stdin. Non-obvious
  findings: `add --note --link ID --body - TITLE`; a problem someone has to fix is a task instead, in the
  repository that has to change.
- `## Project` in `context` is the application's shared context. If it isn't described, or you're asked to set up
  or load the brain, describe it first, from the README and manifests: `project describe -` (what the app is, its
  services and how they connect, conventions they share: the big picture, in at most five lines, without tables,
  columns, function signatures, files or dependencies, which the code already says). Rewrite it when the big
  picture changes (a service added, another storage), not after every change. With several repositories, this
  one's role too: `project notes -`. How to build, test and run this repository, and its code style, go in this
  file, outside this section: add them as you learn them.
- Also: `show ID` (one entry in full), `describe ID TEXT`, `link ID OTHER…` (an id here, or `REPO#ID` in another
  repository of the project); `-` reads text from stdin. Never edit the files in `.brain/` by hand: `kb` keeps
  them consistent.";

/// Makes `root` a repository of project `name` (else the one its card names, else one named after
/// the folder), named `repo` in it (else as [`projects::repo_name`] picks): creates its `.brain/` and card,
/// registers it in `central` (joining the project's other repositories if it has some), creates the project's
/// shared card if it's new, and writes or refreshes the section in each agent file of `root` (creating
/// `CLAUDE.md` if there's none). Returns what it did, one line each.
pub fn init(root: &Path, name: Option<&str>, repo: Option<&str>, central: &Path) -> Result<Vec<String>> {
    let mut done = Vec::new();
    let dir = root.join(PROJECT_DIR);
    if dir.is_dir() {
        done.push(format!("{} already exists", dir.display()));
    } else {
        Store::at(&dir)?;
        done.push(format!("created {}: kanbrain uses it from here and every folder below", dir.display()));
        done.push("commit it to share tasks, notes and decisions with the project, or add it to .gitignore".into());
    }
    // Registered by its absolute path, so the kanban app finds it from anywhere.
    let dir = dir.canonicalize().with_context(|| format!("reading {}", dir.display()))?;
    let folder = root.canonicalize().ok().and_then(|r| Some(r.file_name()?.to_string_lossy().into_owned()));
    let card = projects::read_repo_card(&dir);
    let project = match (name, &card, folder) {
        (Some(name), _, _) => name.to_string(),
        (None, Some(card), _) => card.project.clone(),
        (None, None, Some(folder)) => folder,
        (None, None, None) => bail!("this folder has no name to give the project: `kb init NAME`"),
    };
    projects::check_name(&project)?;
    let named = projects::repo_name(central, &project, &dir, repo)?;
    // The name goes on the card before registering, which tells repositories apart by it; only when it isn't
    // the folder's, so a card stays as it was for the usual case.
    let folder_name = projects::Repo { project: project.clone(), dir: dir.clone() }.folder();
    let notes = card.as_ref().map(|card| card.notes.clone()).unwrap_or_default();
    let new_card =
        projects::RepoCard { project: project.clone(), repo: (named != folder_name).then_some(named), notes };
    if card.as_ref() != Some(&new_card) {
        projects::write_repo_card(&dir, &new_card)?;
    }
    projects::register(central, &project, &dir)?;
    if projects::ensure_description(central, &project)? {
        done.push(format!(
            "created project `{project}`'s card in the central brain: describe the project with `kb project \
             describe` or from the kanban app (or let the agent do it); all its repositories share it"
        ));
    }
    let repos = projects::load(central)?;
    let here =
        repos.iter().find(|r| projects::same_dir(&r.dir, &dir)).map_or_else(|| project.clone(), |r| r.label(&repos));
    let others: Vec<String> = repos
        .iter()
        .filter(|r| r.project == project && !projects::same_dir(&r.dir, &dir))
        .map(projects::Repo::name)
        .collect();
    if others.is_empty() {
        done.push(format!(
            "registered as project `{here}`: the kanban app shows it, and `--project {here}` reaches it"
        ));
    } else {
        done.push(format!(
            "registered as `{here}`, a repository of project `{project}` with {}: they share its card",
            others.join(", ")
        ));
    }
    let existing: Vec<&str> = AGENT_FILES.into_iter().filter(|name| root.join(name).is_file()).collect();
    let targets = if existing.is_empty() { vec![DEFAULT_AGENT_FILE] } else { existing };
    done.extend(write_agent_files(root, &targets)?.into_iter().map(|(_, line)| line));
    if !on_path(std::env::var_os("PATH"), "kb") {
        done.push(
            "`kb` isn't on your PATH, and agents and the hooks run it: install the command line too \
             (the installer's `--app both`)"
                .into(),
        );
    }
    Ok(done)
}

/// Brings every registered repository up to this version: its data format, migrated with the central brain's
/// (see [`crate::migrate`]), and its agent instructions, the section in each of its agent files that has one
/// and Claude Code's hooks where `CLAUDE.md` has it. A repository whose files have no section (taken out by
/// hand) keeps them as they are, and one whose folder is gone is left alone. Returns what changed, one line
/// each, naming the repository.
pub fn init_all(central: &Path) -> Result<Vec<String>> {
    let repos = projects::load(central)?;
    let mut done = migrate_all(central, &repos)?;
    let mut current = 0;
    for repo in repos.iter().filter(|r| r.dir.is_dir()) {
        let Some(root) = repo.dir.parent() else { continue };
        let targets: Vec<&str> = AGENT_FILES
            .into_iter()
            .filter(|name| fs::read_to_string(root.join(name)).is_ok_and(|text| text.contains(START)))
            .collect();
        if targets.is_empty() {
            continue;
        }
        let changes: Vec<String> = write_agent_files(root, &targets)?
            .into_iter()
            .filter(|(changed, _)| *changed)
            .map(|(_, line)| line)
            .collect();
        if changes.is_empty() {
            current += 1;
        }
        let label = repo.label(&repos);
        done.extend(changes.into_iter().map(|line| format!("{label}: {line}")));
    }
    if current > 0 {
        done.push(format!("{current} more already had this version's instructions"));
    }
    Ok(done)
}

/// Brings the central brain and every registered repository's to this version's data format (see
/// [`crate::migrate`]), as `kb update` runs it. A repository a newer kanbrain wrote is said and left alone.
fn migrate_all(central: &Path, repos: &[projects::Repo]) -> Result<Vec<String>> {
    let mut done = crate::migrate::migrate(&Store::at(central)?)?;
    for repo in repos.iter().filter(|r| r.dir.is_dir()) {
        match crate::migrate::migrate(&Store::at(&repo.dir)?) {
            Ok(lines) => done.extend(lines),
            Err(e) if e.downcast_ref::<crate::migrate::TooNew>().is_some() => {
                done.push(format!("{}: left alone: {e}", repo.label(repos)));
            }
            Err(e) => return Err(e),
        }
    }
    Ok(done)
}

/// Writes or updates the section in each of `targets`, agent files of `root`, and Claude Code's hooks when
/// `CLAUDE.md` is one of them. Returns what it did, one line each, and whether that changed anything.
fn write_agent_files(root: &Path, targets: &[&str]) -> Result<Vec<(bool, String)>> {
    let mut done = Vec::new();
    // Claude Code's hooks go with its file; agents that read only AGENTS.md have no use for them.
    if targets.contains(&"CLAUDE.md") {
        done.push(match claude::add_hooks(root) {
            Ok(claude::Change::Unchanged) => (false, format!("{} already has kanbrain's hooks", claude::SETTINGS)),
            Ok(_) => (
                true,
                format!(
                    "added kanbrain's hooks to {}: Claude Code reads `kb context` when a session starts and \
                     after compaction, and an agent can't end its turn while the project isn't described",
                    claude::SETTINGS
                ),
            ),
            // The section still works without them, so a settings file it can't read doesn't stop init.
            Err(e) => (false, format!("left out the Claude Code hooks: {e:#}")),
        });
    }
    for &name in targets {
        let path = root.join(name);
        let before = fs::read_to_string(&path).unwrap_or_default();
        let after = with_section(&before);
        if after == before {
            done.push((false, format!("{name} already tells agents about kanbrain")));
            continue;
        }
        store::write_file(&path, &after)?;
        let what = if before.is_empty() {
            "created"
        } else if before.contains(START) {
            "updated"
        } else {
            "added to"
        };
        done.push((true, format!("{what} {name}: the \"Project memory\" section tells agents how to use the brain")));
    }
    Ok(done)
}

/// Whether a program named `name` is in one of the folders of `path`, a `PATH` value.
fn on_path(path: Option<std::ffi::OsString>, name: &str) -> bool {
    let file = format!("{name}{}", std::env::consts::EXE_SUFFIX);
    path.is_some_and(|path| std::env::split_paths(&path).any(|dir| dir.join(&file).is_file()))
}

/// Takes the repository whose `.brain/` is `dir` out of the project registry, deleting the project's
/// card if it was its last repository, and takes the section out of each agent file of the repository
/// (deleting a file left empty, which `init` created). `.brain/` is left as it is: whether it goes is
/// [`super::manage::remove_repo`]'s. Returns what it did, one line each.
pub fn deinit(dir: &Path, central: &Path) -> Result<Vec<String>> {
    let Some(repo) = projects::unregister(central, dir)? else {
        bail!("{} isn't a registered project: there's nothing to deinit", dir.display());
    };
    let mut done = vec![format!("unregistered {}: the kanban app no longer shows it", repo.dir.display())];
    let others: Vec<String> =
        projects::load(central)?.iter().filter(|r| r.project == repo.project).map(projects::Repo::name).collect();
    if !others.is_empty() {
        done.push(format!(
            "project `{}` keeps its card for its other repositories: {}",
            repo.project,
            others.join(", ")
        ));
    } else if projects::remove_description(central, &repo.project)? {
        done.push(format!("removed project `{}`'s card from the central brain", repo.project));
    }
    let Some(root) = repo.dir.parent().filter(|_| repo.dir.is_dir()) else {
        done.push(format!("{} is gone, so there was nothing else to undo", repo.dir.display()));
        return Ok(done);
    };
    match claude::remove_hooks(root) {
        Ok(claude::Change::Unchanged) => {}
        Ok(claude::Change::Written) => done.push(format!("removed kanbrain's hooks from {}", claude::SETTINGS)),
        Ok(claude::Change::Removed) => done.push(format!("removed {}: it only held the hooks", claude::SETTINGS)),
        Err(e) => done.push(format!("left the Claude Code hooks in place: {e:#}")),
    }
    for name in AGENT_FILES {
        let path = root.join(name);
        let Ok(before) = fs::read_to_string(&path) else { continue };
        let after = without_section(&before);
        if after == before {
            continue;
        }
        if after.trim().is_empty() {
            fs::remove_file(&path).with_context(|| format!("removing {}", path.display()))?;
            done.push(format!("removed {name}: it only held the \"Project memory\" section"));
        } else {
            store::write_file(&path, &after)?;
            done.push(format!("removed the \"Project memory\" section from {name}"));
        }
    }
    Ok(done)
}

/// Where the section is in `text`, with the line break after its end marker. It's the last start
/// marker before the first end marker, so a stray unclosed start marker above it is never taken for
/// the start and the text after it is kept.
fn section(text: &str) -> Option<(usize, usize)> {
    let end = text.find(END)? + END.len();
    let start = text[..end].rfind(START)?;
    Some((start, if text[end..].starts_with('\n') { end + 1 } else { end }))
}

/// `text` with the section between the markers: replaced where it already is, else appended after
/// a blank line.
fn with_section(text: &str) -> String {
    let block = format!("{START}\n{SECTION}\n{END}\n");
    if let Some((start, end)) = section(text) {
        return format!("{}{block}{}", &text[..start], &text[end..]);
    }
    match text.trim_end() {
        "" => block,
        kept => format!("{kept}\n\n{block}"),
    }
}

/// `text` without the section, and without the blank line `with_section` put before it.
fn without_section(text: &str) -> String {
    let Some((start, end)) = section(text) else { return text.to_string() };
    let before = text[..start].trim_end();
    let after = text[end..].trim_start_matches('\n');
    match (before, after) {
        ("", after) => after.to_string(),
        (before, "") => format!("{before}\n"),
        (before, after) => format!("{before}\n\n{after}"),
    }
}

#[cfg(test)]
#[path = "../../tests/cli/init.rs"]
mod tests;