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__':