storkit: merge 432_story_complete_setup_wizard_with_mcp_tools_and_agent_driven_file_generation
This commit is contained in:
dave
@@ -0,0 +1,476 @@
|
||||
//! MCP tool implementations for the interactive setup wizard.
|
||||
//!
|
||||
//! These tools allow Claude Code (and other MCP clients) to drive the setup
|
||||
//! wizard entirely from the terminal without requiring the web UI or chat bot.
|
||||
//!
|
||||
//! Typical flow:
|
||||
//! 1. `wizard_status` — inspect current state
|
||||
//! 2. `wizard_generate` — read the codebase and call again with `content` to
|
||||
//! stage generated text for review
|
||||
//! 3. `wizard_confirm` — write staged content to disk and advance the wizard
|
||||
//! 4. `wizard_skip` — skip a step that does not apply
|
||||
//! 5. `wizard_retry` — discard staged content and regenerate from scratch
|
||||
|
||||
use crate::http::context::AppContext;
|
||||
use crate::io::wizard::{StepStatus, WizardState, WizardStep, format_wizard_state};
|
||||
use serde_json::Value;
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
|
||||
// ── helpers ───────────────────────────────────────────────────────────────────
|
||||
|
||||
/// Return the filesystem path (relative to `project_root`) for a step's output.
|
||||
///
|
||||
/// Returns `None` for `Scaffold` since that step has no single output file — it
|
||||
/// creates the full `.storkit/` directory structure and is handled by
|
||||
/// `storkit init` before the server starts.
|
||||
pub(crate) fn step_output_path(project_root: &Path, step: WizardStep) -> Option<std::path::PathBuf> {
|
||||
match step {
|
||||
WizardStep::Context => Some(
|
||||
project_root
|
||||
.join(".storkit")
|
||||
.join("specs")
|
||||
.join("00_CONTEXT.md"),
|
||||
),
|
||||
WizardStep::Stack => Some(
|
||||
project_root
|
||||
.join(".storkit")
|
||||
.join("specs")
|
||||
.join("tech")
|
||||
.join("STACK.md"),
|
||||
),
|
||||
WizardStep::TestScript => Some(project_root.join("script").join("test")),
|
||||
WizardStep::ReleaseScript => Some(project_root.join("script").join("release")),
|
||||
WizardStep::TestCoverage => Some(project_root.join("script").join("test_coverage")),
|
||||
WizardStep::Scaffold => None,
|
||||
}
|
||||
}
|
||||
|
||||
pub(crate) fn is_script_step(step: WizardStep) -> bool {
|
||||
matches!(
|
||||
step,
|
||||
WizardStep::TestScript | WizardStep::ReleaseScript | WizardStep::TestCoverage
|
||||
)
|
||||
}
|
||||
|
||||
/// Write `content` to `path` only when the file does not already exist.
|
||||
///
|
||||
/// Existing files (including `CLAUDE.md`) are never overwritten — the wizard
|
||||
/// appends or skips per the acceptance criteria. For script steps the file is
|
||||
/// also made executable after writing.
|
||||
pub(crate) fn write_if_missing(path: &Path, content: &str, executable: bool) -> Result<bool, String> {
|
||||
if path.exists() {
|
||||
return Ok(false); // already present — skip silently
|
||||
}
|
||||
if let Some(parent) = path.parent() {
|
||||
fs::create_dir_all(parent)
|
||||
.map_err(|e| format!("Failed to create directory {}: {e}", parent.display()))?;
|
||||
}
|
||||
fs::write(path, content)
|
||||
.map_err(|e| format!("Failed to write {}: {e}", path.display()))?;
|
||||
|
||||
if executable {
|
||||
#[cfg(unix)]
|
||||
{
|
||||
use std::os::unix::fs::PermissionsExt;
|
||||
let mut perms = fs::metadata(path)
|
||||
.map_err(|e| format!("Failed to read permissions: {e}"))?
|
||||
.permissions();
|
||||
perms.set_mode(0o755);
|
||||
fs::set_permissions(path, perms)
|
||||
.map_err(|e| format!("Failed to set permissions: {e}"))?;
|
||||
}
|
||||
}
|
||||
|
||||
Ok(true)
|
||||
}
|
||||
|
||||
/// Serialise a `WizardStep` to its snake_case string (e.g. `"test_script"`).
|
||||
fn step_slug(step: WizardStep) -> String {
|
||||
serde_json::to_value(step)
|
||||
.ok()
|
||||
.and_then(|v| v.as_str().map(String::from))
|
||||
.unwrap_or_default()
|
||||
}
|
||||
|
||||
// ── MCP tool handlers ─────────────────────────────────────────────────────────
|
||||
|
||||
/// `wizard_status` — return current wizard state as a human-readable summary.
|
||||
pub(super) fn tool_wizard_status(ctx: &AppContext) -> Result<String, String> {
|
||||
let root = ctx.state.get_project_root()?;
|
||||
let state =
|
||||
WizardState::load(&root).ok_or("No wizard active. Run `storkit init` to begin setup.")?;
|
||||
Ok(format_wizard_state(&state))
|
||||
}
|
||||
|
||||
/// `wizard_generate` — mark the current step as generating or stage content.
|
||||
///
|
||||
/// Call with no `content` argument to mark the step as `Generating` and
|
||||
/// receive a hint describing what to generate. Call again with a `content`
|
||||
/// argument (the generated file body) to stage it for review; the step will
|
||||
/// transition to `AwaitingConfirmation`. Content is **not** written to disk
|
||||
/// until `wizard_confirm` is called.
|
||||
pub(super) fn tool_wizard_generate(args: &Value, ctx: &AppContext) -> Result<String, String> {
|
||||
let root = ctx.state.get_project_root()?;
|
||||
let mut state = WizardState::load(&root).ok_or("No wizard active.")?;
|
||||
|
||||
if state.completed {
|
||||
return Ok("Wizard is already complete.".to_string());
|
||||
}
|
||||
|
||||
let current_idx = state.current_step_index();
|
||||
let step = state.steps[current_idx].step;
|
||||
|
||||
// If content is provided, stage it for confirmation.
|
||||
if let Some(content) = args.get("content").and_then(|v| v.as_str()) {
|
||||
state.set_step_status(
|
||||
step,
|
||||
StepStatus::AwaitingConfirmation,
|
||||
Some(content.to_string()),
|
||||
);
|
||||
state
|
||||
.save(&root)
|
||||
.map_err(|e| format!("Failed to save wizard state: {e}"))?;
|
||||
return Ok(format!(
|
||||
"Content staged for '{}'. Run `wizard_confirm` to write it to disk, `wizard_retry` to regenerate, or `wizard_skip` to skip.",
|
||||
step.label()
|
||||
));
|
||||
}
|
||||
|
||||
// No content provided — mark as generating and return a hint.
|
||||
state.set_step_status(step, StepStatus::Generating, None);
|
||||
state
|
||||
.save(&root)
|
||||
.map_err(|e| format!("Failed to save wizard state: {e}"))?;
|
||||
|
||||
let hint = generation_hint(step, &root);
|
||||
let slug = step_slug(step);
|
||||
|
||||
Ok(format!(
|
||||
"Step '{}' marked as generating.\n\n{hint}\n\nOnce you have the content, call `wizard_generate` again with a `content` argument (or PUT /wizard/step/{slug}/content). Then call `wizard_confirm` to write it to disk.",
|
||||
step.label(),
|
||||
))
|
||||
}
|
||||
|
||||
/// Return a generation hint for a step based on the project root.
|
||||
fn generation_hint(step: WizardStep, project_root: &Path) -> String {
|
||||
match step {
|
||||
WizardStep::Context => {
|
||||
"Read the project source tree and generate a `.storkit/specs/00_CONTEXT.md` describing:\n\
|
||||
- High-level goal of the project\n\
|
||||
- Core features\n\
|
||||
- Domain concepts and entities\n\
|
||||
- Glossary of abbreviations and technical terms".to_string()
|
||||
}
|
||||
WizardStep::Stack => {
|
||||
"Read the project source tree and generate a `.storkit/specs/tech/STACK.md` describing:\n\
|
||||
- Language, frameworks, and runtimes\n\
|
||||
- Coding standards and linting rules\n\
|
||||
- Quality gates (commands that must pass before merging)\n\
|
||||
- Approved libraries and their purpose".to_string()
|
||||
}
|
||||
WizardStep::TestScript => {
|
||||
let has_cargo = project_root.join("Cargo.toml").exists();
|
||||
let has_pkg = project_root.join("package.json").exists();
|
||||
let has_pnpm = project_root.join("pnpm-lock.yaml").exists();
|
||||
let mut cmds = Vec::new();
|
||||
if has_cargo {
|
||||
cmds.push("cargo nextest run");
|
||||
}
|
||||
if has_pkg {
|
||||
cmds.push(if has_pnpm { "pnpm test" } else { "npm test" });
|
||||
}
|
||||
if cmds.is_empty() {
|
||||
"Generate a `script/test` shell script (#!/usr/bin/env bash, set -euo pipefail) that runs the project's test suite.".to_string()
|
||||
} else {
|
||||
format!(
|
||||
"Generate a `script/test` shell script (#!/usr/bin/env bash, set -euo pipefail) that runs: {}",
|
||||
cmds.join(", ")
|
||||
)
|
||||
}
|
||||
}
|
||||
WizardStep::ReleaseScript => {
|
||||
"Generate a `script/release` shell script (#!/usr/bin/env bash, set -euo pipefail) that builds and releases the project (e.g. `cargo build --release` or `npm run build`).".to_string()
|
||||
}
|
||||
WizardStep::TestCoverage => {
|
||||
"Generate a `script/test_coverage` shell script (#!/usr/bin/env bash, set -euo pipefail) that generates a test coverage report (e.g. `cargo llvm-cov nextest` or `npm run coverage`).".to_string()
|
||||
}
|
||||
WizardStep::Scaffold => "Scaffold step is handled automatically by `storkit init`.".to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
/// `wizard_confirm` — confirm the current step and write its content to disk.
|
||||
///
|
||||
/// If the step has staged content, the content is written to its target file
|
||||
/// (only if that file does not already exist — existing files are never
|
||||
/// overwritten). The step is then marked as `Confirmed` and the wizard
|
||||
/// advances to the next pending step.
|
||||
pub(super) fn tool_wizard_confirm(ctx: &AppContext) -> Result<String, String> {
|
||||
let root = ctx.state.get_project_root()?;
|
||||
let mut state = WizardState::load(&root).ok_or("No wizard active.")?;
|
||||
|
||||
if state.completed {
|
||||
return Ok("Wizard is already complete.".to_string());
|
||||
}
|
||||
|
||||
let current_idx = state.current_step_index();
|
||||
let step = state.steps[current_idx].step;
|
||||
let content = state.steps[current_idx].content.clone();
|
||||
|
||||
// Write content to disk (only if a file path exists and the file is absent).
|
||||
let write_msg = if let (Some(c), Some(ref path)) = (&content, step_output_path(&root, step)) {
|
||||
let executable = is_script_step(step);
|
||||
match write_if_missing(path, c, executable)? {
|
||||
true => format!(" File written: `{}`.", path.display()),
|
||||
false => format!(" File `{}` already exists — skipped.", path.display()),
|
||||
}
|
||||
} else {
|
||||
String::new()
|
||||
};
|
||||
|
||||
state
|
||||
.confirm_step(step)
|
||||
.map_err(|e| format!("Cannot confirm step: {e}"))?;
|
||||
state
|
||||
.save(&root)
|
||||
.map_err(|e| format!("Failed to save wizard state: {e}"))?;
|
||||
|
||||
let next_idx = state.current_step_index();
|
||||
if state.completed {
|
||||
Ok(format!(
|
||||
"Step '{}' confirmed.{write_msg}\n\nSetup wizard complete! All steps done.",
|
||||
step.label()
|
||||
))
|
||||
} else {
|
||||
let next = &state.steps[next_idx];
|
||||
Ok(format!(
|
||||
"Step '{}' confirmed.{write_msg}\n\nNext: {} — run `wizard_generate` to begin.",
|
||||
step.label(),
|
||||
next.step.label()
|
||||
))
|
||||
}
|
||||
}
|
||||
|
||||
/// `wizard_skip` — skip the current step without writing any file.
|
||||
pub(super) fn tool_wizard_skip(ctx: &AppContext) -> Result<String, String> {
|
||||
let root = ctx.state.get_project_root()?;
|
||||
let mut state = WizardState::load(&root).ok_or("No wizard active.")?;
|
||||
|
||||
if state.completed {
|
||||
return Ok("Wizard is already complete.".to_string());
|
||||
}
|
||||
|
||||
let current_idx = state.current_step_index();
|
||||
let step = state.steps[current_idx].step;
|
||||
|
||||
state
|
||||
.skip_step(step)
|
||||
.map_err(|e| format!("Cannot skip step: {e}"))?;
|
||||
state
|
||||
.save(&root)
|
||||
.map_err(|e| format!("Failed to save wizard state: {e}"))?;
|
||||
|
||||
let next_idx = state.current_step_index();
|
||||
if state.completed {
|
||||
Ok(format!(
|
||||
"Step '{}' skipped. Setup wizard complete!",
|
||||
step.label()
|
||||
))
|
||||
} else {
|
||||
let next = &state.steps[next_idx];
|
||||
Ok(format!(
|
||||
"Step '{}' skipped.\n\nNext: {} — run `wizard_generate` to begin.",
|
||||
step.label(),
|
||||
next.step.label()
|
||||
))
|
||||
}
|
||||
}
|
||||
|
||||
/// `wizard_retry` — discard staged content and reset the current step to
|
||||
/// `Pending` so it can be regenerated.
|
||||
pub(super) fn tool_wizard_retry(ctx: &AppContext) -> Result<String, String> {
|
||||
let root = ctx.state.get_project_root()?;
|
||||
let mut state = WizardState::load(&root).ok_or("No wizard active.")?;
|
||||
|
||||
if state.completed {
|
||||
return Ok("Wizard is already complete.".to_string());
|
||||
}
|
||||
|
||||
let current_idx = state.current_step_index();
|
||||
let step = state.steps[current_idx].step;
|
||||
|
||||
// Clear content and reset to pending.
|
||||
if let Some(s) = state.steps.iter_mut().find(|s| s.step == step) {
|
||||
s.status = StepStatus::Pending;
|
||||
s.content = None;
|
||||
}
|
||||
state
|
||||
.save(&root)
|
||||
.map_err(|e| format!("Failed to save wizard state: {e}"))?;
|
||||
|
||||
Ok(format!(
|
||||
"Step '{}' reset to pending. Run `wizard_generate` to regenerate content.",
|
||||
step.label()
|
||||
))
|
||||
}
|
||||
|
||||
// ── tests ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::http::context::AppContext;
|
||||
use tempfile::TempDir;
|
||||
|
||||
fn setup(dir: &TempDir) -> AppContext {
|
||||
let root = dir.path().to_path_buf();
|
||||
std::fs::create_dir_all(root.join(".storkit")).unwrap();
|
||||
WizardState::init_if_missing(&root);
|
||||
AppContext::new_test(root)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_status_returns_state() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
let ctx = setup(&dir);
|
||||
let result = tool_wizard_status(&ctx).unwrap();
|
||||
assert!(result.contains("Setup wizard"));
|
||||
assert!(result.contains("context"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_status_no_wizard_returns_error() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
|
||||
let ctx = AppContext::new_test(dir.path().to_path_buf());
|
||||
assert!(tool_wizard_status(&ctx).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_generate_marks_generating() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
let ctx = setup(&dir);
|
||||
let result = tool_wizard_generate(&serde_json::json!({}), &ctx).unwrap();
|
||||
assert!(result.contains("generating"));
|
||||
let state = WizardState::load(dir.path()).unwrap();
|
||||
assert_eq!(state.steps[1].status, StepStatus::Generating);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_generate_with_content_stages_content() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
let ctx = setup(&dir);
|
||||
let result = tool_wizard_generate(
|
||||
&serde_json::json!({"content": "# My Project"}),
|
||||
&ctx,
|
||||
)
|
||||
.unwrap();
|
||||
assert!(result.contains("staged"));
|
||||
let state = WizardState::load(dir.path()).unwrap();
|
||||
assert_eq!(state.steps[1].status, StepStatus::AwaitingConfirmation);
|
||||
assert_eq!(state.steps[1].content.as_deref(), Some("# My Project"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_confirm_writes_file_and_advances() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
let ctx = setup(&dir);
|
||||
// Stage content for Context step.
|
||||
tool_wizard_generate(
|
||||
&serde_json::json!({"content": "# Context content"}),
|
||||
&ctx,
|
||||
)
|
||||
.unwrap();
|
||||
let result = tool_wizard_confirm(&ctx).unwrap();
|
||||
assert!(result.contains("confirmed"));
|
||||
// File should now exist.
|
||||
let context_path = dir
|
||||
.path()
|
||||
.join(".storkit")
|
||||
.join("specs")
|
||||
.join("00_CONTEXT.md");
|
||||
assert!(context_path.exists());
|
||||
assert_eq!(
|
||||
std::fs::read_to_string(&context_path).unwrap(),
|
||||
"# Context content"
|
||||
);
|
||||
// Wizard should have advanced.
|
||||
let state = WizardState::load(dir.path()).unwrap();
|
||||
assert_eq!(state.steps[1].status, StepStatus::Confirmed);
|
||||
assert_eq!(state.current_step_index(), 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_confirm_does_not_overwrite_existing_file() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
let ctx = setup(&dir);
|
||||
// Pre-create the specs directory and file.
|
||||
let specs_dir = dir.path().join(".storkit").join("specs");
|
||||
std::fs::create_dir_all(&specs_dir).unwrap();
|
||||
let context_path = specs_dir.join("00_CONTEXT.md");
|
||||
std::fs::write(&context_path, "original content").unwrap();
|
||||
|
||||
// Stage and confirm — existing file should NOT be overwritten.
|
||||
tool_wizard_generate(
|
||||
&serde_json::json!({"content": "new content"}),
|
||||
&ctx,
|
||||
)
|
||||
.unwrap();
|
||||
let result = tool_wizard_confirm(&ctx).unwrap();
|
||||
assert!(result.contains("already exists"));
|
||||
assert_eq!(
|
||||
std::fs::read_to_string(&context_path).unwrap(),
|
||||
"original content"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_skip_advances_wizard() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
let ctx = setup(&dir);
|
||||
let result = tool_wizard_skip(&ctx).unwrap();
|
||||
assert!(result.contains("skipped"));
|
||||
let state = WizardState::load(dir.path()).unwrap();
|
||||
assert_eq!(state.steps[1].status, StepStatus::Skipped);
|
||||
assert_eq!(state.current_step_index(), 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_retry_resets_to_pending() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
let ctx = setup(&dir);
|
||||
// Stage content first.
|
||||
tool_wizard_generate(
|
||||
&serde_json::json!({"content": "some content"}),
|
||||
&ctx,
|
||||
)
|
||||
.unwrap();
|
||||
let result = tool_wizard_retry(&ctx).unwrap();
|
||||
assert!(result.contains("reset"));
|
||||
let state = WizardState::load(dir.path()).unwrap();
|
||||
assert_eq!(state.steps[1].status, StepStatus::Pending);
|
||||
assert!(state.steps[1].content.is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wizard_complete_returns_done_message() {
|
||||
let dir = TempDir::new().unwrap();
|
||||
let ctx = setup(&dir);
|
||||
// Skip all remaining steps.
|
||||
for _ in 0..5 {
|
||||
tool_wizard_skip(&ctx).unwrap();
|
||||
}
|
||||
let result = tool_wizard_status(&ctx).unwrap();
|
||||
assert!(result.contains("complete"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn format_wizard_state_shows_all_steps() {
|
||||
let mut state = WizardState::default();
|
||||
state.steps[0].status = StepStatus::Confirmed;
|
||||
let output = format_wizard_state(&state);
|
||||
assert!(output.contains("✓"));
|
||||
assert!(output.contains("Scaffold"));
|
||||
assert!(output.contains("← current"));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user