feat(convert): --force to overwrite existing contracts; commas in messages

Add `apic convert --postman --force`; the default still errors on an existing
file and now suggests --force. Sweep user-facing messages to use commas instead
of semicolons and em-dashes.

Author: rizukirr

CHANGELOG.md

@@ -7,11 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `apic convert --postman` gains a `--force` flag to overwrite contracts that
+  already exist. The default still refuses (erroring on an existing file), and
+  the error now points to `--force`.
+
 ### Changed
 - **Contract format (breaking).** A request body is now the raw JSON payload
   written directly under `request` (no `example` wrapper), and a response body is
   written under the response's `schema` key (renamed from `example`). Contracts
   using the previous `{ "example": ... }` body shape must be updated.
+- User-facing messages use commas instead of semicolons and em-dashes.
 
 ## [0.4.0] - 2026-07-06
 

README.md

@@ -364,11 +364,13 @@ v1.0.0, v2.0.0, and v2.1.0 (auto-detected).
 - `--destination <dir>`, where to write the contracts, relative to the working
   directory (created if missing). **Optional**, defaults to the working
   directory itself. The path is confined to the working directory (`..`/absolute
-  escapes are rejected) and existing files are never overwritten.
+  escapes are rejected). An existing contract is left untouched (the import
+  errors) unless `--force` is passed.
+- `--force`, overwrite contracts that already exist instead of erroring.
 
 Each Postman folder becomes a directory and each request becomes
 `folder/request_name.json`. Only the fields apic models are imported (method,
-URL, headers, request/response bodies); Postman-specific data (auth blocks,
+URL, headers, request/response bodies), Postman-specific data (auth blocks,
 scripts, events, variables) is ignored. A request whose HTTP method apic does
 not model (anything other than `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`HEAD`/
 `OPTIONS`) is imported as `GET` with a warning, so nothing is downgraded
@@ -378,6 +380,7 @@ silently.
 apic init                                   # an apic project is required
 apic convert --postman MyAPI.postman.json   # writes into the working directory
 apic convert --postman MyAPI.postman.json --destination imported
+apic convert --postman MyAPI.postman.json --force   # overwrite existing contracts
 ```
 
 ```text

apic-core/src/convert.rs

@@ -178,7 +178,7 @@ fn method_warning(method: &str, name: &str) -> Option<String> {
         None
     } else {
         Some(format!(
-            "request {name:?} uses method {upper}, unsupported by apic — imported as GET"
+            "request {name:?} uses method {upper}, unsupported by apic, imported as GET"
         ))
     }
 }
@@ -456,15 +456,20 @@ fn map(collection: &PostmanCollection) -> Vec<MappedContract> {
 
 /// Write mapped contracts under `dest_base`. Each contract's `rel_path` is
 /// confined under `dest_base` (rejecting `..` escapes), its parent directories
-/// are created, and the pretty-printed JSON is written. Existing files are not
-/// overwritten. Returns the number of files written.
-fn write_contracts(dest_base: &Path, mapped: &[MappedContract]) -> Result<usize, String> {
+/// are created, and the pretty-printed JSON is written. An existing file is left
+/// untouched (erroring) unless `overwrite` is set. Returns the number of files
+/// written.
+fn write_contracts(
+    dest_base: &Path,
+    mapped: &[MappedContract],
+    overwrite: bool,
+) -> Result<usize, String> {
     let mut written = 0usize;
     for item in mapped {
         let path = confine_to_dir(dest_base, &item.rel_path)?;
-        if path.exists() {
+        if !overwrite && path.exists() {
             return Err(format!(
-                "{} already exists; refusing to overwrite",
+                "{} already exists, pass --force to overwrite",
                 path.display()
             ));
         }
@@ -490,13 +495,17 @@ pub struct ConvertOutcome {
 
 /// Parses the collection at `collection_path`, maps it, writes contracts under
 /// `dest_base`, and returns what happened. Does not print — the caller reports.
-pub fn run(collection_path: &Path, dest_base: &Path) -> Result<ConvertOutcome, String> {
+pub fn run(
+    collection_path: &Path,
+    dest_base: &Path,
+    overwrite: bool,
+) -> Result<ConvertOutcome, String> {
     let collection = converter::from_path(collection_path)?;
     let mapped = map(&collection);
     if mapped.is_empty() {
         return Err("collection contained no convertible requests".to_string());
     }
-    let written = write_contracts(dest_base, &mapped)?;
+    let written = write_contracts(dest_base, &mapped, overwrite)?;
     let warnings: Vec<String> = mapped.iter().filter_map(|m| m.warning.clone()).collect();
     Ok(ConvertOutcome {
         written,
@@ -821,13 +830,18 @@ mod tests {
             warning: None,
         }];
 
-        let n = write_contracts(&base, &mapped).unwrap();
+        let n = write_contracts(&base, &mapped, false).unwrap();
         assert_eq!(n, 1);
         assert!(base.join("users").join("get_user.json").is_file());
 
-        // Second write to the same path is refused.
-        let err = write_contracts(&base, &mapped).unwrap_err();
+        // Second write to the same path is refused, and points to --force.
+        let err = write_contracts(&base, &mapped, false).unwrap_err();
         assert!(err.contains("already exists"));
+        assert!(err.contains("--force"));
+
+        // With overwrite, the same path is rewritten instead of erroring.
+        let n = write_contracts(&base, &mapped, true).unwrap();
+        assert_eq!(n, 1);
 
         std::fs::remove_dir_all(&base).unwrap();
     }

apic-core/src/template.rs

@@ -154,7 +154,7 @@ fn resolve_at(apic_dir: &Path) -> Result<(String, Vec<String>), String> {
     if let Err(err) = seed_if_missing(apic_dir) {
         return Ok((
             DEFAULT.to_string(),
-            vec![format!("{err}; using the built-in template")],
+            vec![format!("{err}, using the built-in template")],
         ));
     }
     resolve_contract_from(&resolve_path(apic_dir))
@@ -173,7 +173,7 @@ pub fn resolve_contract_from(path: &Path) -> Result<(String, Vec<String>), Strin
             return Ok((
                 DEFAULT.to_string(),
                 vec![format!(
-                    "failed to read {}: {err}; using the built-in template",
+                    "failed to read {}: {err}, using the built-in template",
                     path.display()
                 )],
             ));

apic-gui/src/desktop.rs

@@ -117,7 +117,7 @@ pub fn install_desktop_entry() -> Result<String, String> {
 /// Non-Linux: launcher integration is handled by platform package managers.
 #[cfg(not(target_os = "linux"))]
 pub fn install_desktop_entry() -> Result<String, String> {
-    Err("--desktop-entry is Linux-only. On macOS install via Homebrew (or use the .app from Releases); on Windows use winget (or the .exe from Releases).".to_string())
+    Err("--desktop-entry is Linux-only. On macOS install via Homebrew (or use the .app from Releases), on Windows use winget (or the .exe from Releases).".to_string())
 }
 
 #[cfg(all(test, target_os = "linux"))]

apic-gui/src/main.rs

@@ -552,7 +552,9 @@ impl App {
             self.status = "no project to import into".into();
             return;
         };
-        match apic_core::convert::run(&src, &root) {
+        // The GUI import never overwrites; existing contracts must be removed
+        // first (or edited), matching the CLI default.
+        match apic_core::convert::run(&src, &root, false) {
             Ok(out) => {
                 self.reload_project();
                 let warn = if out.warnings.is_empty() {
@@ -706,7 +708,7 @@ impl App {
 
         if !is_folder {
             if dest.exists() {
-                self.status = format!("{rel} already exists; not overwriting");
+                self.status = format!("{rel} already exists, not overwriting");
                 return;
             }
             // Seed from the chosen template (merged onto the built-in default),
@@ -775,7 +777,7 @@ impl App {
                 }
                 ui.add_space(SPACE_EXTRA_SMALL);
                 ui.label(
-                    RichText::new("end with .json for a contract (auth/logout.json); a bare name makes a folder")
+                    RichText::new("end with .json for a contract (auth/logout.json), a bare name makes a folder")
                         .color(DIM)
                         .size(10.0),
                 );
@@ -1261,7 +1263,7 @@ impl App {
                 ui.add_space(SPACE_SMALL);
                 if rep.error.is_empty() {
                     ui.label(
-                        RichText::new("Valid — opening editor…")
+                        RichText::new("Valid, opening editor…")
                             .color(GREEN)
                             .strong(),
                     );
@@ -1578,7 +1580,7 @@ impl TreeNode {
             ui.horizontal(|ui| {
                 if *invalid {
                     ui.label(RichText::new("●").color(RED))
-                        .on_hover_text("Invalid contract — click to repair");
+                        .on_hover_text("Invalid contract, click to repair");
                 }
                 ui.label(RichText::new(method).color(method_color(method)).size(11.0));
                 // Reserve the delete button on the right, then let the file name

src/cli.rs

@@ -215,9 +215,9 @@ enum Commands {
     /// one JSON contract per request, mirroring the collection's folder nesting.
     /// Files are written under `--destination`, resolved within the configured
     /// working directory; when omitted, the working directory itself is used.
-    /// `..` escapes and absolute paths elsewhere are rejected, and existing
-    /// files are never overwritten. Requires an initialized apic project
-    /// (`apic init`).
+    /// `..` escapes and absolute paths elsewhere are rejected. An existing
+    /// contract is left untouched unless `--force` is passed. Requires an
+    /// initialized apic project (`apic init`).
     Convert {
         /// Path to the Postman collection JSON file to import.
         #[arg(long, value_name = "FILE")]
@@ -228,6 +228,10 @@ enum Commands {
         /// directory from `.apic/config.toml`.
         #[arg(long, value_name = "DIR")]
         destination: Option<String>,
+
+        /// Overwrite contracts that already exist instead of erroring.
+        #[arg(long)]
+        force: bool,
     },
 }
 
@@ -260,7 +264,7 @@ fn init_cmd(working_dir: Option<&str>) -> Result<(), String> {
             println!("Successfully initialized");
         }
         InitOutcome::TemplateSeeded => {
-            println!("Already initialized; created the missing template")
+            println!("Already initialized, created the missing template")
         }
     }
     Ok(())
@@ -467,9 +471,9 @@ fn select_create_template(
 fn no_template_error(name: &str, templates: &[PathBuf], root: &Path) -> String {
     let mut msg = format!("no template matching '{}'", sanitize(name));
     if templates.is_empty() {
-        msg.push_str("; no templates in .apic/template/");
+        msg.push_str(", no templates in .apic/template/");
     } else {
-        msg.push_str("; available:\n");
+        msg.push_str(", available:\n");
         for t in templates {
             msg.push_str(&format!("  {}\n", rel_display(t, root)));
         }
@@ -772,7 +776,7 @@ fn validate_cmd(template: bool, find: Option<&str>) -> Result<(), String> {
                 if issues.is_empty() {
                     Ok(())
                 } else {
-                    Err(issues.join("; "))
+                    Err(issues.join(", "))
                 }
             });
 
@@ -804,13 +808,13 @@ fn validate_template_cmd() -> Result<(), String> {
     let apic_dir = match apic_core::config::find_apic_dir() {
         Some(dir) => dir,
         None => {
-            println!("No project template found; create will use the built-in template");
+            println!("No project template found, create will use the built-in template");
             return Ok(());
         }
     };
     let templates = apic_core::template::list_templates(&apic_dir);
     if templates.is_empty() {
-        println!("No project template found; create will use the built-in template");
+        println!("No project template found, create will use the built-in template");
         return Ok(());
     }
 
@@ -1108,13 +1112,13 @@ fn remove_template_cmd(name: &str) -> Result<(), String> {
 
 /// Handles `apic convert`: resolve the destination under the working directory,
 /// then parse the Postman collection and write contracts.
-fn convert_cmd(postman: &Path, destination: Option<&str>) -> Result<(), String> {
+fn convert_cmd(postman: &Path, destination: Option<&str>, force: bool) -> Result<(), String> {
     let root = read_config_file().and_then(|conf| conf.get_root_dir())?;
     let dest_base = match destination {
         Some(dir) => confine_to_dir(&root, Path::new(dir))?,
         None => root,
     };
-    let outcome = apic_core::convert::run(postman, &dest_base)?;
+    let outcome = apic_core::convert::run(postman, &dest_base, force)?;
     for warning in &outcome.warnings {
         eprintln!("warning: {warning}");
     }
@@ -1294,7 +1298,8 @@ pub(crate) fn run() {
         Commands::Convert {
             postman,
             destination,
-        } => convert_cmd(&postman, destination.as_deref()),
+            force,
+        } => convert_cmd(&postman, destination.as_deref(), force),
     };
 
     if let Err(err) = result {

src/render.rs

@@ -133,9 +133,9 @@ impl Printer {
                 b'4' | b'5' => code.red().bold(),
                 _ => code.yellow().bold(),
             };
-            println!(" {} {code} — {description}", "RESPONSE".bold());
+            println!(" {} {code}, {description}", "RESPONSE".bold());
         } else {
-            println!(" RESPONSE {code} — {description}");
+            println!(" RESPONSE {code}, {description}");
         }
     }
 

src/tui/draw.rs

@@ -808,15 +808,15 @@ fn draw_help(frame: &mut Frame, area: Rect) {
             "Move between cells · switch response tabs",
         ]),
         Row::new(vec!["Enter", "Edit cell · open example"]),
-        Row::new(vec!["i", "Insert — edit the focused text cell"]),
+        Row::new(vec!["i", "Insert, edit the focused text cell"]),
         Row::new(vec!["Esc", "Back · cancel"]),
         Row::new(vec![
             "a",
             "Add row · REQUEST writes JSON · RESPONSE new-response form",
         ]),
         Row::new(vec![
             "e",
-            "Edit — response tab: status/title · body: JSON example",
+            "Edit, response tab: status/title · body: JSON example",
         ]),
         Row::new(vec!["d", "Delete the selected row"]),
         Row::new(vec!["Ctrl-S", "Save"]),