From 7d85685f84989132afda46cadb92328c191e0b5e Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Sat, 14 Nov 2026 14:42:41 +0000 Subject: [PATCH 1/3] Guide first-use commands and prioritize qualified typo suggestions --- rust/parity/cases.json | 105 ++++++++++++++++++++++-- rust/parity/catalog-updates.json | 6 ++ rust/parity/parity.py | 5 ++ rust/parity/test_parity.py | 15 ++++ rust/src/catalog.json | 2 +- rust/src/descriptor/txt.rs | 136 +++++++++++++++++++++++++++---- rust/src/lookup.rs | 51 ++++++++++-- 7 files changed, 290 insertions(+), 30 deletions(-) diff --git a/rust/parity/cases.json b/rust/parity/cases.json index 974c1747..dfa330a1 100644 --- a/rust/parity/cases.json +++ b/rust/parity/cases.json @@ -543,14 +543,30 @@ "name": "unknown command in a known namespace", "argv": [ "env:nope" - ] + ], + "expected_difference": { + "*": { + "fields": [ + "stderr" + ], + "reason": "Qualified command typos prioritize the nearest name in the requested namespace (cli#159)." + } + } }, { "name": "typo with several suggestions", "argv": [ "env:lst", "-n" - ] + ], + "expected_difference": { + "*": { + "fields": [ + "stderr" + ], + "reason": "Qualified command typos prioritize the nearest name in the requested namespace (cli#159)." + } + } }, { "name": "typo with one suggestion, no interaction", @@ -617,11 +633,27 @@ "name": "list", "argv": [ "list" - ] + ], + "expected_difference": { + "*": { + "fields": [ + "stdout_text" + ], + "reason": "Human command discovery begins with six common commands and connection guidance (cli#159)." + } + } }, { "name": "no arguments lists commands", - "argv": [] + "argv": [], + "expected_difference": { + "*": { + "fields": [ + "stdout_text" + ], + "reason": "Human command discovery begins with six common commands and connection guidance (cli#159)." + } + } }, { "name": "list one namespace", @@ -670,7 +702,15 @@ }, "argv": [ "env:nope" - ] + ], + "expected_difference": { + "*": { + "fields": [ + "stderr" + ], + "reason": "Qualified command typos prioritize the nearest name in the requested namespace (cli#159)." + } + } }, { "name": "server:info json", @@ -899,7 +939,15 @@ "argv": [ "workflow:start", "--help" - ] + ], + "expected_difference": { + "*": { + "fields": [ + "stdout_text" + ], + "reason": "Human workflow:start help puts its first example and common controls before advanced options (cli#159)." + } + } }, { "name": "help for a command with array options", @@ -947,7 +995,15 @@ "argv": [ "help", "env:lst" - ] + ], + "expected_difference": { + "*": { + "fields": [ + "stderr" + ], + "reason": "Qualified command typos prioritize the nearest name in the requested namespace (cli#159)." + } + } }, { "name": "help without a command", @@ -1215,7 +1271,15 @@ "argv": [ "list", "--ansi" - ] + ], + "expected_difference": { + "*": { + "fields": [ + "stdout_text" + ], + "reason": "Human command discovery begins with six common commands and connection guidance (cli#159)." + } + } }, { "name": "ansi version", @@ -1294,7 +1358,15 @@ "argv": [ "list", "--no-ansi" - ] + ], + "expected_difference": { + "*": { + "fields": [ + "stdout_text" + ], + "reason": "Human command discovery begins with six common commands and connection guidance (cli#159)." + } + } }, { "name": "quiet command", @@ -22765,6 +22837,21 @@ "--json" ], "server": true + }, + { + "name": "workflow typo prioritizes its own list command", + "argv": [ + "workflow:lst", + "-n" + ], + "expected_difference": { + "*": { + "fields": [ + "stderr" + ], + "reason": "workflow:lst suggests workflow:list first while preserving the lookup failure and noninteractive behavior (cli#159)." + } + } } ] } diff --git a/rust/parity/catalog-updates.json b/rust/parity/catalog-updates.json index 3389b444..ecbbd781 100644 --- a/rust/parity/catalog-updates.json +++ b/rust/parity/catalog-updates.json @@ -411,5 +411,11 @@ } } } + }, + "workflow:start": { + "help": { + "reference": "Start a workflow by type. The server accepts JSON input, memo, and\nsearch attributes. With --wait the command blocks until\nthe workflow reaches a terminal state and exits with\nSUCCESS (0) on completion or FAILURE (1) on\nfailure / cancellation / termination.\n\nStart commands are deduped by workflow_command_id. If the\ncaller retries after a network error it must send the same command id so\nthe engine recognises the retry. The --duplicate-policy\noption controls what happens when a second start targets an existing\nworkflow_instance_id (e.g. reject_duplicate\nreturns a duplicate outcome, return_existing_active\nreturns the existing active run's identity).\n\nThe new run is pinned to the starter process's compatibility marker\n(DW_V2_CURRENT_COMPATIBILITY) exactly once at start. Retry\nruns, continue-as-new runs, and child workflows inherit that marker so the\nrun stays inside one compatibility family for its whole lifecycle. Only\nworkers whose DW_V2_SUPPORTED_COMPATIBILITIES set includes\nthe run's marker (or the workers-only * wildcard) will\nclaim the run's tasks; any other worker rejects the claim at claim time\nwith compatibility_blocked or\ncompatibility_unsupported and the task stays on the queue\nfor a compatible worker to pick up.\n\nExamples:\n\n # Start with no input\n dw workflow:start --type=orders.Checkout\n\n # Start with JSON input and a custom workflow id\n dw workflow:start -t orders.Checkout -w chk-42 -i '{\"order_id\":42}'\n\n # Start, then wait for terminal state\n dw workflow:start -t orders.Checkout -i '{\"order_id\":42}' --wait\n\n # Start with search attributes for visibility filters\n dw workflow:start -t orders.Checkout --search-attr env=prod --search-attr tier=gold", + "candidate": "Start a workflow by type. The server accepts JSON input, memo, and\nsearch attributes. With --wait the command blocks until\nthe workflow reaches a terminal state and exits with\nSUCCESS (0) on completion or FAILURE (1) on\nfailure / cancellation / termination.\n\nExamples:\n\n # Start with no input\n dw workflow:start --type=orders.Checkout\n\n # Start with JSON input and a custom workflow id\n dw workflow:start -t orders.Checkout -w chk-42 -i '{\"order_id\":42}'\n\n # Start, then wait for terminal state\n dw workflow:start -t orders.Checkout -i '{\"order_id\":42}' --wait\n\n # Start with search attributes for visibility filters\n dw workflow:start -t orders.Checkout --search-attr env=prod --search-attr tier=gold\n\n # Print the start response as JSON\n dw workflow:start --type=orders.Checkout --output=json\n\nUse --output=json for JSON. --json is its alias.\n\nAdvanced behavior:\n\nStart commands are deduped by workflow_command_id. If the\ncaller retries after a network error it must send the same command id so\nthe engine recognises the retry. The --duplicate-policy\noption controls what happens when a second start targets an existing\nworkflow_instance_id (e.g. reject_duplicate\nreturns a duplicate outcome, return_existing_active\nreturns the existing active run's identity).\n\nThe new run is pinned to the starter process's compatibility marker\n(DW_V2_CURRENT_COMPATIBILITY) exactly once at start. Retry\nruns, continue-as-new runs, and child workflows inherit that marker so the\nrun stays inside one compatibility family for its whole lifecycle. Only\nworkers whose DW_V2_SUPPORTED_COMPATIBILITIES set includes\nthe run's marker (or the workers-only * wildcard) will\nclaim the run's tasks; any other worker rejects the claim at claim time\nwith compatibility_blocked or\ncompatibility_unsupported and the task stays on the queue\nfor a compatible worker to pick up." + } } } diff --git a/rust/parity/parity.py b/rust/parity/parity.py index 21bde675..088456fd 100755 --- a/rust/parity/parity.py +++ b/rust/parity/parity.py @@ -556,6 +556,11 @@ def help_cases(): "fields": ["stdout_text"], "reason": "The help accurately describes one Server response page and an unconsumed cursor (cli#113).", }} + if case["argv"][0] == "workflow:start": + case["expected_difference"] = {"*": { + "fields": ["stdout_text"], + "reason": "Human workflow:start help puts its first example and common controls before advanced options (cli#159).", + }} if case["argv"][0] == "workflow:signal": # --request-id is PHP main's (cli#61); published 2.3.5 lacks it. case["reference"] = "php-main" diff --git a/rust/parity/test_parity.py b/rust/parity/test_parity.py index 11fd68be..21c92039 100644 --- a/rust/parity/test_parity.py +++ b/rust/parity/test_parity.py @@ -167,6 +167,21 @@ def test_markdown_style_removal_keeps_the_exact_owned_help_change(self): self.normalize("target:command\nafter help\n", "candidate")) +class HumanHelpDifferenceScopeTest(unittest.TestCase): + def test_display_changes_cannot_hide_exit_json_or_config_regressions(self): + with open(parity.CASES, encoding="utf-8") as handle: + cases = json.load(handle)["cases"] + parity.help_cases() + for case in cases: + expected = case.get("expected_difference", {}).get("*", {}) + if "cli#159" not in expected.get("reason", ""): + continue + fields = expected["fields"] + self.assertIn(fields, [["stdout_text"], ["stderr"]]) + self.assertIsNotNone(parity.intentional_reason(case, fields)) + for extra in ["exit_code", "stdout_json", "config", "stderr_category"]: + self.assertIsNone(parity.intentional_reason(case, [*fields, extra])) + + class PhpMainReferenceTest(unittest.TestCase): def setUp(self): self.directories = list(parity.BIN_DIRECTORIES) diff --git a/rust/src/catalog.json b/rust/src/catalog.json index 66d41909..f6e6a4fe 100644 --- a/rust/src/catalog.json +++ b/rust/src/catalog.json @@ -14449,7 +14449,7 @@ "synopsis": "workflow:start [-s|--server [SERVER]] [--namespace [NAMESPACE]] [--token [TOKEN]] [--tls-verify TLS-VERIFY] [--env ENV] [--output OUTPUT] [-t|--type TYPE] [-w|--workflow-id [WORKFLOW-ID]] [--business-key [BUSINESS-KEY]] [--task-queue [TASK-QUEUE]] [--duplicate-policy [DUPLICATE-POLICY]] [--memo [MEMO]] [--search-attr [SEARCH-ATTR]] [--execution-timeout EXECUTION-TIMEOUT] [--run-timeout RUN-TIMEOUT] [--priority PRIORITY] [--fairness-key FAIRNESS-KEY] [--fairness-weight FAIRNESS-WEIGHT] [--wait] [--json] [-i|--input [INPUT]] [--input-file [INPUT-FILE]] [--input-encoding [INPUT-ENCODING]]", "aliases": [], "hidden": false, - "help": "Start a workflow by type. The server accepts JSON input, memo, and\nsearch attributes. With --wait the command blocks until\nthe workflow reaches a terminal state and exits with\nSUCCESS (0) on completion or FAILURE (1) on\nfailure / cancellation / termination.\n\nStart commands are deduped by workflow_command_id. If the\ncaller retries after a network error it must send the same command id so\nthe engine recognises the retry. The --duplicate-policy\noption controls what happens when a second start targets an existing\nworkflow_instance_id (e.g. reject_duplicate\nreturns a duplicate outcome, return_existing_active\nreturns the existing active run's identity).\n\nThe new run is pinned to the starter process's compatibility marker\n(DW_V2_CURRENT_COMPATIBILITY) exactly once at start. Retry\nruns, continue-as-new runs, and child workflows inherit that marker so the\nrun stays inside one compatibility family for its whole lifecycle. Only\nworkers whose DW_V2_SUPPORTED_COMPATIBILITIES set includes\nthe run's marker (or the workers-only * wildcard) will\nclaim the run's tasks; any other worker rejects the claim at claim time\nwith compatibility_blocked or\ncompatibility_unsupported and the task stays on the queue\nfor a compatible worker to pick up.\n\nExamples:\n\n # Start with no input\n dw workflow:start --type=orders.Checkout\n\n # Start with JSON input and a custom workflow id\n dw workflow:start -t orders.Checkout -w chk-42 -i '{\"order_id\":42}'\n\n # Start, then wait for terminal state\n dw workflow:start -t orders.Checkout -i '{\"order_id\":42}' --wait\n\n # Start with search attributes for visibility filters\n dw workflow:start -t orders.Checkout --search-attr env=prod --search-attr tier=gold", + "help": "Start a workflow by type. The server accepts JSON input, memo, and\nsearch attributes. With --wait the command blocks until\nthe workflow reaches a terminal state and exits with\nSUCCESS (0) on completion or FAILURE (1) on\nfailure / cancellation / termination.\n\nExamples:\n\n # Start with no input\n dw workflow:start --type=orders.Checkout\n\n # Start with JSON input and a custom workflow id\n dw workflow:start -t orders.Checkout -w chk-42 -i '{\"order_id\":42}'\n\n # Start, then wait for terminal state\n dw workflow:start -t orders.Checkout -i '{\"order_id\":42}' --wait\n\n # Start with search attributes for visibility filters\n dw workflow:start -t orders.Checkout --search-attr env=prod --search-attr tier=gold\n\n # Print the start response as JSON\n dw workflow:start --type=orders.Checkout --output=json\n\nUse --output=json for JSON. --json is its alias.\n\nAdvanced behavior:\n\nStart commands are deduped by workflow_command_id. If the\ncaller retries after a network error it must send the same command id so\nthe engine recognises the retry. The --duplicate-policy\noption controls what happens when a second start targets an existing\nworkflow_instance_id (e.g. reject_duplicate\nreturns a duplicate outcome, return_existing_active\nreturns the existing active run's identity).\n\nThe new run is pinned to the starter process's compatibility marker\n(DW_V2_CURRENT_COMPATIBILITY) exactly once at start. Retry\nruns, continue-as-new runs, and child workflows inherit that marker so the\nrun stays inside one compatibility family for its whole lifecycle. Only\nworkers whose DW_V2_SUPPORTED_COMPATIBILITIES set includes\nthe run's marker (or the workers-only * wildcard) will\nclaim the run's tasks; any other worker rejects the claim at claim time\nwith compatibility_blocked or\ncompatibility_unsupported and the task stays on the queue\nfor a compatible worker to pick up.", "definition": { "arguments": [], "options": { diff --git a/rust/src/descriptor/txt.rs b/rust/src/descriptor/txt.rs index aa01c4bb..3bf7ee67 100644 --- a/rust/src/descriptor/txt.rs +++ b/rust/src/descriptor/txt.rs @@ -174,15 +174,18 @@ fn describe_definition(writer: &mut Writer, options: &[&OptionView], arguments: writer.text("\n"); } if !options.is_empty() { - writer.text("Options:"); - // Options with a multi-letter shortcut (-v|vv|vvv) come last. - let (later, first): (Vec<&&OptionView>, Vec<&&OptionView>) = options - .iter() - .partition(|option| option.shortcut.chars().count() > 1); - for option in first.into_iter().chain(later) { - writer.text("\n"); - describe_option(writer, option, total_width); - } + describe_options(writer, options, total_width, "Options"); + } +} + +fn describe_options(writer: &mut Writer, options: &[&OptionView], total_width: usize, title: &str) { + writer.text(&format!("{title}:")); + let (later, first): (Vec<&&OptionView>, Vec<&&OptionView>) = options + .iter() + .partition(|option| option.shortcut.chars().count() > 1); + for option in first.into_iter().chain(later) { + writer.text("\n"); + describe_option(writer, option, total_width); } } @@ -203,10 +206,47 @@ pub fn command(view: &CommandView, raw: bool) -> String { writer.text(&format!(" {}", formatter::escape(&usage))); } writer.text("\n"); + let starting_workflow = view.entry.name == "workflow:start" && !raw; + if starting_workflow { + writer.text("\nQuick start:\n"); + writer.text(" dw workflow:start --type=orders.Checkout\n"); + writer.text(" Use a workflow type registered by your application's Worker.\n"); + writer.text(" Add --wait to wait for completion. Use --output=json for JSON.\n"); + } if !view.options.is_empty() || !view.arguments.is_empty() { writer.text("\n"); - let options: Vec<&OptionView> = view.options.iter().collect(); - describe_definition(&mut writer, &options, &view.arguments); + if starting_workflow { + let names = [ + "type", + "input", + "workflow-id", + "task-queue", + "wait", + "output", + "env", + "help", + ]; + let common: Vec<_> = names + .iter() + .filter_map(|name| view.options.iter().find(|option| option.name == *name)) + .collect(); + let advanced: Vec<_> = view + .options + .iter() + .filter(|option| !names.contains(&option.name.as_str())) + .collect(); + describe_definition(&mut writer, &common, &view.arguments); + writer.text("\n\n"); + let width = advanced + .iter() + .map(|option| option_width(option)) + .max() + .unwrap_or(0); + describe_options(&mut writer, &advanced, width, "Advanced options"); + } else { + let options: Vec<&OptionView> = view.options.iter().collect(); + describe_definition(&mut writer, &options, &view.arguments); + } writer.text("\n"); } if !view.help.is_empty() && view.help != *description { @@ -237,10 +277,26 @@ fn application_options() -> Vec { } /// The `-h`/`--help` … `--verbose` block every listing starts with. -fn describe_application_header(writer: &mut Writer) { +fn describe_application_header(writer: &mut Writer, start_here: bool) { writer.text(&format!("{}\n\n", long_version())); writer.text("Usage:\n"); writer.text(" command [options] [arguments]\n\n"); + if start_here { + writer.text("Start here:\n"); + for (name, description) in [ + ("server:start-dev", "Start a local Server"), + ("env:set", "Save a connection profile"), + ("doctor", "Check your connection"), + ("workflow:start", "Start a workflow"), + ("workflow:list", "Find your workflows"), + ("workflow:describe", "Inspect a workflow"), + ] { + writer.text(&format!(" {name:20} {description}\n")); + } + writer.text("\n Use dw help workflow:start for options and examples.\n\n"); + writer.text(" Run dw doctor to inspect the target Server.\n"); + writer.text(" Save a profile with dw env:set; the default target is localhost:8080.\n\n"); + } let options = application_options(); let refs: Vec<&OptionView> = options.iter().collect(); describe_definition(writer, &refs, &[]); @@ -252,7 +308,7 @@ fn describe_application_header(writer: &mut Writer) { /// `list` namespace. pub fn application_header() -> String { let mut writer = Writer::new(false); - describe_application_header(&mut writer); + describe_application_header(&mut writer, false); writer.out } @@ -276,7 +332,7 @@ pub fn application(described: Option<&str>, raw: bool) -> String { return writer.out; } - describe_application_header(&mut writer); + describe_application_header(&mut writer, described.is_none()); // When describing one namespace, its aliases are listed too. let listed: Vec<&str> = match &resolved { Some(_) => view @@ -348,6 +404,36 @@ mod tests { formatter::format(text, false) } + #[test] + fn default_human_listing_has_a_short_starting_path_before_all_commands() { + let page = plain(&application(None, false)); + let start = page.find("Start here:").unwrap(); + let end = start + page[start..].find("\n\n").unwrap(); + let first_steps = &page[start..end]; + for name in [ + "server:start-dev", + "env:set", + "doctor", + "workflow:start", + "workflow:list", + "workflow:describe", + ] { + assert!(first_steps.contains(name)); + assert!(catalog::entry(name).is_some()); + } + assert_eq!( + first_steps + .lines() + .filter(|line| line.starts_with(" ") && !line.starts_with(" Use")) + .count(), + 6 + ); + assert!(end < page.find("Available commands:").unwrap()); + assert!(!application(None, true).contains("Start here:")); + assert!(!application(Some("workflow"), false).contains("Start here:")); + assert!(!application_header().contains("Start here:")); + } + #[test] fn env_use_help_matches_2x() { let page = plain(&command( @@ -367,6 +453,28 @@ mod tests { assert!(page.ends_with(" dw env:use prod --json\n")); } + #[test] + fn workflow_start_help_begins_with_an_example_and_separates_advanced_options() { + let view = CommandView::new(catalog::entry("workflow:start").unwrap()); + let page = plain(&command(&view, false)); + let common = page.find("Options:").unwrap(); + let advanced = page.find("Advanced options:").unwrap(); + assert!(page.find("dw workflow:start --type=").unwrap() < common); + assert!(common < page.find("--type=TYPE").unwrap()); + assert!(page.find("--output=OUTPUT").unwrap() < advanced); + for option in [ + "--priority", + "--fairness-key", + "--duplicate-policy", + "--json", + ] { + assert!(page.find(option).unwrap() > advanced); + } + let raw = plain(&command(&view, true)); + assert!(!raw.contains("Advanced options:")); + assert!(!raw.contains("Quick start:")); + } + #[test] fn styles_mark_headings_and_names() { let page = command(&CommandView::new(catalog::entry("env:use").unwrap()), false); diff --git a/rust/src/lookup.rs b/rust/src/lookup.rs index cd82ac4c..479ba7c6 100644 --- a/rust/src/lookup.rs +++ b/rust/src/lookup.rs @@ -1,6 +1,7 @@ //! Command lookup with the 2.x (Symfony Console) rules: exact names and //! aliases, unambiguous abbreviations per `:` segment (`env:li`, `e:l`), -//! and the same "not defined", "ambiguous" and "Did you mean" messages. +//! and the same error categories. Typo suggestions put nearby commands in +//! the requested namespace first. use crate::catalog; use std::cmp::Ordering; @@ -251,10 +252,24 @@ pub fn find(name: &str, terminal_width: usize) -> Result { if let Some(position) = name.rfind(':') { find_namespace(&name[..position])?; } - let visible: Vec = alternatives(name, &all) + let mut visible: Vec = alternatives(name, &all) .into_iter() .filter(|candidate| !canonical(candidate).hidden) .collect(); + // A typo within a known namespace should offer its nearest command + // first. Alphabetical sorting buries workflow:list below unrelated + // commands that happen to share its final segment. + if let Some((namespace, _)) = name.rsplit_once(':') { + visible.sort_by(|left, right| { + let same_namespace = |candidate: &str| { + candidate.rsplit_once(':').map(|(prefix, _)| prefix) == Some(namespace) + }; + same_namespace(right) + .cmp(&same_namespace(left)) + .then_with(|| levenshtein(name, left).cmp(&levenshtein(name, right))) + .then_with(|| natural_case_cmp(left, right)) + }); + } let message = format!( "Command \"{name}\" is not defined.{}", did_you_mean(&visible) @@ -355,10 +370,34 @@ mod tests { alternatives: vec!["env:list".into()], } ); - assert!(find("env:lst", 80) - .unwrap_err() - .message() - .starts_with("Command \"env:lst\" is not defined.\n\nDid you mean one of these?\n activities:list\n activity:list\n")); + assert!(find("env:lst", 80).unwrap_err().message().starts_with( + "Command \"env:lst\" is not defined.\n\nDid you mean one of these?\n env:list\n" + )); + } + + #[test] + fn command_typos_prioritize_the_requested_namespace_and_nearest_name() { + for (typo, wanted) in [ + ("workflow:lst", "workflow:list"), + ("env:lst", "env:list"), + ("activity:lst", "activity:list"), + ] { + let LookupError::NotFound { alternatives, .. } = find(typo, 80).unwrap_err() else { + panic!("expected command suggestions for {typo}"); + }; + assert_eq!(alternatives.first().map(String::as_str), Some(wanted)); + assert!(alternatives.iter().all(|name| !canonical(name).hidden)); + } + // Suggesting a command must never silently dispatch it. + assert_eq!(find("e:li", 80).unwrap(), "env:list"); + assert_eq!(find("workflows:list", 80).unwrap(), "workflow:list"); + let LookupError::NotFound { alternatives, .. } = find("sch", 80).unwrap_err() else { + panic!("expected the existing namespace suggestions"); + }; + assert_eq!( + alternatives.first().map(String::as_str), + Some("schedule:backfill") + ); } #[test] From 9e6bde1044edf6848a9f1adb4c5e7a8be1f7e96c Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:06:05 +0000 Subject: [PATCH 2/3] Include workflow history in the first-use path --- rust/src/descriptor/txt.rs | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/rust/src/descriptor/txt.rs b/rust/src/descriptor/txt.rs index 3bf7ee67..9f466a3f 100644 --- a/rust/src/descriptor/txt.rs +++ b/rust/src/descriptor/txt.rs @@ -285,11 +285,11 @@ fn describe_application_header(writer: &mut Writer, start_here: bool) { writer.text("Start here:\n"); for (name, description) in [ ("server:start-dev", "Start a local Server"), - ("env:set", "Save a connection profile"), ("doctor", "Check your connection"), ("workflow:start", "Start a workflow"), ("workflow:list", "Find your workflows"), ("workflow:describe", "Inspect a workflow"), + ("workflow:history", "Read a workflow's history"), ] { writer.text(&format!(" {name:20} {description}\n")); } @@ -412,22 +412,16 @@ mod tests { let first_steps = &page[start..end]; for name in [ "server:start-dev", - "env:set", "doctor", "workflow:start", "workflow:list", "workflow:describe", + "workflow:history", ] { assert!(first_steps.contains(name)); assert!(catalog::entry(name).is_some()); } - assert_eq!( - first_steps - .lines() - .filter(|line| line.starts_with(" ") && !line.starts_with(" Use")) - .count(), - 6 - ); + assert!(page[..page.find("Options:").unwrap()].contains("dw env:set")); assert!(end < page.find("Available commands:").unwrap()); assert!(!application(None, true).contains("Start here:")); assert!(!application(Some("workflow"), false).contains("Start here:")); From 20d547b207f4f1acccdde4cb70863a6209c66023 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:35:44 +0000 Subject: [PATCH 3/3] Exercise saved-profile onboarding with the standalone native binary --- rust/README.md | 7 ++-- scripts/ci/smoke-native-dev.py | 58 ++++++++++++++++++++++++++-------- 2 files changed, 49 insertions(+), 16 deletions(-) diff --git a/rust/README.md b/rust/README.md index 91041e0a..ce346406 100644 --- a/rust/README.md +++ b/rust/README.md @@ -21,7 +21,7 @@ command is ported. | `env:list`, `env:set`, `env:use`, `env:show`, `env:delete` | Ported | | `server:health`, `server:info` (and `cluster:info`) | Ported | | Compatibility preflight, session and `--version` warnings, exit 8 refusals | Ported | -| `server:start-dev`: local Laravel launch, Compose prerequisites and Unix signal cleanup | Ported | +| `server:start-dev`: built-in native Server, SQLite, private persistent data and shutdown | No external runtime or separate Server installation | | `runtime:check`: native build identity and compilation target | Ported, intentional output/help difference | | `doctor`: redacted connection sources, server metadata, warnings and next steps | Ported | | `workflow:list`: one namespace/page, filters, Server envelopes, JSON and JSONL | Ported | @@ -46,8 +46,9 @@ command is ported. | `task-queue:pause-activities`, `task-queue:resume-activities`, `task-queue:activity-dispatch`: pause, resume and read activity dispatch on one task queue (Server #577), one request each after checking cluster info for `capabilities.task_queue_activity_dispatch_pause`; `task-queue:describe` and `task-queue:list` show the state when the Server reports it | Rust-only, new | | `workflow:update-outcome`: read an update's outcome later by its update ID (Server #1131, durable-workflow/.github#212), one GET after checking cluster info for `capabilities.update_outcome_reads`; pending, completed (including a null result), failed (exit 2), rejected and `update_not_found` (exit 5) are reported distinctly, and the update is never sent again. `workflow:update` points an unfinished update at it when the Server advertises the capability | Rust-only, new | -Server calls go through the published `durable-workflow` crate, pinned to -the latest qualified release. +Server calls go through the `durable-workflow` crate. The unreleased native +development Server also links the Server library; exact dependency revisions +are recorded in `Cargo.toml` and `Cargo.lock`. `workflow:list-runs` sends its workflow ID as one percent-encoded SDK path segment. IDs containing slashes, query delimiters or fragments stay within diff --git a/scripts/ci/smoke-native-dev.py b/scripts/ci/smoke-native-dev.py index 1e73afd0..d92837fe 100644 --- a/scripts/ci/smoke-native-dev.py +++ b/scripts/ci/smoke-native-dev.py @@ -77,9 +77,10 @@ def readiness(port, expected_status=200): def cli(binary, root, environment, port, arguments): + target = [] if port is None else [f'--server=http://127.0.0.1:{port}', + '--token=dev-token'] result = subprocess.run( - [str(binary), *arguments, f'--server=http://127.0.0.1:{port}', - '--token=dev-token', '--output=json'], + [str(binary), *arguments, *target, '--output=json'], cwd=root, env=environment, stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=15, check=False, ) @@ -88,6 +89,40 @@ def cli(binary, root, environment, port, arguments): return json.loads(result.stdout) +def profile(binary, root, environment, port): + saved = cli(binary, root, environment, None, ['env:set', 'local', + f'--server=http://127.0.0.1:{port}', '--token=dev-token', '--make-default']) + if saved.get('name') != 'local' or saved.get('current') is not True: + raise RuntimeError('local profile was not selected') + diagnostic = cli(binary, root, environment, None, ['doctor']) + connection = diagnostic.get('connection', {}) + if (diagnostic.get('server', {}).get('reachable') is not True + or connection.get('profile', {}).get('name') != 'local' + or connection.get('server') != f'http://127.0.0.1:{port}'): + raise RuntimeError('doctor did not reach the Server through the saved profile') + + +def read_workflow(binary, root, environment, run_id=None): + listing = cli(binary, root, environment, None, ['workflow:list']) + if not any(row.get('workflow_id') == 'cli-asset-smoke' + for row in listing.get('workflows', [])): + raise RuntimeError('new workflow was not listed through the profile') + workflow = cli(binary, root, environment, None, + ['workflow:describe', 'cli-asset-smoke']) + if workflow.get('workflow_id') != 'cli-asset-smoke': + raise RuntimeError('new workflow was not visible') + for name in ['run_id', 'workflow_type', 'status']: + if not isinstance(workflow.get(name), str) or not workflow[name]: + raise RuntimeError('missing workflow identity/state: '+name) + if run_id is not None and workflow['run_id'] != run_id: + raise RuntimeError('workflow run changed over restart') + history = cli(binary, root, environment, None, + ['workflow:history', 'cli-asset-smoke', workflow['run_id']]) + if not isinstance(history.get('events'), list) or not history['events']: + raise RuntimeError('workflow history was not visible through the profile') + return workflow, history['events'] + + def private_state_refusals(binary, root, environment): # Seed each case through the real command first. A refusal caused merely by # an incorrectly prepared ACL/directory would not test the malicious entry. @@ -161,25 +196,22 @@ def main(): pass else: raise RuntimeError('a held development directory could be replaced') - cli(binary, root, environment, port, ['workflow:start', '--type=cli.asset-smoke', + profile(binary, root, environment, port) + cli(binary, root, environment, None, ['workflow:start', '--type=cli.asset-smoke', '--workflow-id=cli-asset-smoke', '--input={}']) - before = cli(binary, root, environment, port, ['workflow:describe', 'cli-asset-smoke']) - if before.get('workflow_id') != 'cli-asset-smoke': - raise RuntimeError('new workflow was not visible') - for name in ['run_id', 'workflow_type', 'status']: - if not isinstance(before.get(name), str) or not before[name]: - raise RuntimeError('missing workflow identity/state: '+name) + before, history_before = read_workflow(binary, root, environment) finally: stop(process, reader) process, reader, port = start(binary, root, environment) try: readiness(port) - after = cli(binary, root, environment, port, ['workflow:describe', 'cli-asset-smoke']) + profile(binary, root, environment, port) + after, history_after = read_workflow(binary, root, environment, before['run_id']) for name in ['workflow_id', 'run_id', 'workflow_type', 'status']: if before.get(name) != after.get(name): raise RuntimeError('workflow identity/state changed over restart: '+name) - if 'cli-asset-smoke' not in json.dumps(after): - raise RuntimeError('workflow did not survive restart') + if history_before != history_after: + raise RuntimeError('workflow history changed over restart') finally: stop(process, reader) observation = root/'observation.json' @@ -195,7 +227,7 @@ def main(): finally: stop(process, reader) private_state_refusals(binary, root, environment) - print('Built-in native Server: empty PATH, readiness, workflow admission, restart and platform admission PASS') + print('Built-in native Server: empty PATH, profile, doctor, start/list/describe/history, restart and platform admission PASS') if __name__ == '__main__':