setup: Implement setup orchestration and flake-level verification

Wire `sce setup` to execute repository-root installation for resolved targets,
  replace placeholder setup messaging with deterministic completion output,
  and mark setup as implemented in the command surface.

Add focused parser/run-path coverage and integrate a dedicated CLI setup
  command-surface check into `nix flake check`.

Author: davidabram

cli/README.md

@@ -3,9 +3,9 @@
 This crate provides the early command-surface scaffold for the Shared Context
 Engineering CLI (`sce`).
 
-Current scope is intentionally narrow: deterministic command dispatch, explicit
-placeholder messaging, and service contracts that reserve future implementation
-seams.
+Current scope is intentionally narrow: deterministic command dispatch, an
+implemented repository `setup` flow, and explicit placeholders for commands
+that are still deferred.
 
 ## Quick start
 
@@ -20,7 +20,15 @@ cargo run --manifest-path cli/Cargo.toml -- sync
 ## Current behavior
 
 - `help` is implemented and prints the current command surface.
-- `setup` is a placeholder that returns a deferred setup-plan message.
+- `setup` is implemented:
+  - default mode is interactive target selection (`OpenCode`, `Claude`,
+    `Both`) via `inquire`
+  - non-interactive mode is available with one mutually-exclusive flag:
+    `--opencode`, `--claude`, or `--both`
+  - setup assets are embedded at compile time from `config/.opencode/**` and
+    `config/.claude/**`
+  - installation writes to repository-root `.opencode/` and/or `.claude/`
+    using backup-and-replace safety with rollback on swap failures
 - `mcp` is a placeholder for future file-cache tooling contracts
   (`cache-put`/`cache-get`).
 - `hooks` is a placeholder for future git hook event and generated-region
@@ -30,8 +38,8 @@ cargo run --manifest-path cli/Cargo.toml -- sync
 
 ## Safety and limitations
 
-- Placeholder commands do not perform repository setup, MCP transport, hook
-  installation, or cloud sync.
+- `mcp`, `hooks`, and `sync` remain placeholders and do not perform MCP
+  transport, hook installation, or cloud sync.
 - `sync` only validates local adapter wiring and does not require remote auth.
 - This crate is scaffolding for incremental delivery and should not be treated
   as production-ready workflow automation.
@@ -53,3 +61,10 @@ cargo check --manifest-path cli/Cargo.toml
 cargo test --manifest-path cli/Cargo.toml
 cargo build --manifest-path cli/Cargo.toml
 ```
+
+Run repository flake checks (includes targeted setup command-surface checks from
+`cli/`):
+
+```bash
+nix flake check
+```

cli/flake.lock

@@ -0,0 +1,62 @@
+{
+  description = "SCE CLI flake";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+      flake-utils,
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
+      let
+        pkgs = import nixpkgs {
+          inherit system;
+        };
+      in
+      {
+        checks.cli-setup-command-surface = pkgs.rustPlatform.buildRustPackage {
+          pname = "sce-cli-setup-command-surface-check";
+          version = "0.1.0";
+          src = builtins.path {
+            path = ../.;
+            name = "source";
+          };
+          sourceRoot = "source/cli";
+
+          cargoLock = {
+            lockFile = ../cli/Cargo.lock;
+          };
+
+          nativeBuildInputs = [ pkgs.rustfmt ];
+
+          buildPhase = ''
+            runHook preBuild
+            runHook postBuild
+          '';
+
+          checkPhase = ''
+            runHook preCheck
+
+            cargo fmt --check
+            cargo test command_surface::tests::help_text_mentions_setup_target_flags
+            cargo test parser_routes_setup
+            cargo test run_setup_reports
+
+            runHook postCheck
+          '';
+
+          installPhase = ''
+            runHook preInstall
+            mkdir -p "$out"
+            runHook postInstall
+          '';
+        };
+      }
+    );
+}

cli/flake.nix

@@ -1,7 +1,7 @@
 use std::process::ExitCode;
 
 use crate::{command_surface, dependency_contract, services};
-use anyhow::{bail, Result};
+use anyhow::{bail, Context, Result};
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 enum Command {
@@ -130,7 +130,12 @@ fn dispatch(command: Command) -> Result<()> {
 
             match dispatch {
                 services::setup::SetupDispatch::Proceed(mode) => {
-                    println!("{}", services::setup::run_placeholder_setup_for_mode(mode)?);
+                    let repository_root =
+                        std::env::current_dir().context("Failed to determine current directory")?;
+                    println!(
+                        "{}",
+                        services::setup::run_setup_for_mode(&repository_root, mode)?
+                    );
                 }
                 services::setup::SetupDispatch::Cancelled => {
                     println!("{}", services::setup::setup_cancelled_text());
@@ -161,12 +166,8 @@ mod tests {
     }
 
     #[test]
-    fn placeholder_command_exits_success() {
-        let code = run(vec![
-            "sce".to_string(),
-            "setup".to_string(),
-            "--opencode".to_string(),
-        ]);
+    fn hooks_command_exits_success() {
+        let code = run(vec!["sce".to_string(), "hooks".to_string()]);
         assert_eq!(code, ExitCode::SUCCESS);
     }
 
@@ -219,6 +220,34 @@ mod tests {
         );
     }
 
+    #[test]
+    fn parser_routes_setup_claude_flag_to_non_interactive_mode() {
+        let command = parse_command(vec![
+            "sce".to_string(),
+            "setup".to_string(),
+            "--claude".to_string(),
+        ])
+        .expect("command should parse");
+        assert_eq!(
+            command,
+            Command::Setup(SetupMode::NonInteractive(SetupTarget::Claude,))
+        );
+    }
+
+    #[test]
+    fn parser_routes_setup_both_flag_to_non_interactive_mode() {
+        let command = parse_command(vec![
+            "sce".to_string(),
+            "setup".to_string(),
+            "--both".to_string(),
+        ])
+        .expect("command should parse");
+        assert_eq!(
+            command,
+            Command::Setup(SetupMode::NonInteractive(SetupTarget::Both,))
+        );
+    }
+
     #[test]
     fn parser_routes_setup_without_flags_to_interactive_mode() {
         let command = parse_command(vec!["sce".to_string(), "setup".to_string()])

cli/src/app.rs

@@ -21,7 +21,7 @@ pub const COMMANDS: &[CommandContract] = &[
     },
     CommandContract {
         name: services::setup::NAME,
-        status: ImplementationStatus::Placeholder,
+        status: ImplementationStatus::Implemented,
         purpose: "Prepare local repository/workspace prerequisites",
     },
     CommandContract {
@@ -67,7 +67,9 @@ pub fn help_text() -> String {
     out.push_str(
         "\nSetup defaults to interactive target selection when no setup target flag is passed.\n",
     );
-    out.push_str("Only command-surface scaffolding is implemented in this task slice.\n");
+    out.push_str(
+        "`setup` is implemented; `mcp`, `hooks`, and `sync` remain placeholder-oriented.\n",
+    );
     out
 }