onetaskgraph 0.3.12

//! The command line, and the configuration layer it contributes.
//!
//! Flags are the highest of the three layers, and every setting is reachable here —
//! including every field of every named source, through `--set`. That is what makes
//! the product scriptable: a caller who can name a setting in a document can name the
//! same setting on the command line, at the same dotted path.

use std::num::NonZeroU32;
use std::str::FromStr;

use chrono::{DateTime, Utc};
use clap::{Args, Parser, Subcommand, ValueEnum};
use onetaskgraph_core::config::{Layer, Origin, Setting, SettingPath, value_from_text};
use onetaskgraph_core::{GlobalId, OutputFormat, PluginKind, SearchKind};
use onetaskgraph_plugin_api::{
    Classification, Direction, MetadataMatch, NativeId, Priority, Repository, StatusCategory,
    TextFields,
};
use serde_json::Value;

/// One interface over the ticketing systems your work lives in.
///
/// Exit codes: `0` on success, `1` when a command failed while running, `2` when the
/// invocation itself was wrong (clap's own code for that), `4` when a query succeeded
/// for some sources and failed for others without `--allow-partial`, or when a write landed
/// and a task it delivers could not be kept in step with it. `0` means success
/// and nothing else: a run that reached no source, or lost one, never exits `0` unless
/// you asked for a partial answer.
#[derive(Debug, Parser)]
// `bin_name` is pinned rather than left to clap, which takes it from argv[0] — and on
// Windows argv[0] is `onetaskgraph.exe`, so the usage line would name a different command
// there than the one this declares and than the one the documentation tells a user to type.
#[command(name = "onetaskgraph", bin_name = "onetaskgraph", version)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Command,

    #[command(flatten)]
    pub overrides: Overrides,
}

/// The verbs this binary answers.
#[derive(Debug, Subcommand)]
pub enum Command {
    /// Host one compiled-in source over the stdio plugin protocol.
    #[command(hide = true)]
    PluginServe {
        /// The compiled-in plugin kind to host.
        source: PluginKind,
    },

    /// Print the JSON Schema bundle the contract types generate.
    ///
    /// Both SDKs are generated from this document, so it is emitted from the
    /// running binary rather than committed: the schema and the types that
    /// serialise cannot drift when they are the same types.
    Schema,

    /// Work with the configuration this command reads.
    Config {
        #[command(subcommand)]
        command: ConfigCommand,
    },

    /// Work with the sources this configuration names.
    Sources {
        #[command(subcommand)]
        command: SourcesCommand,
    },

    /// List, show and walk tasks.
    Task {
        #[command(subcommand)]
        command: TaskCommand,
    },

    /// List, show and walk projects.
    Project {
        #[command(subcommand)]
        command: ProjectCommand,
    },

    /// List, show and copy documents.
    ///
    /// A document is not work: it has no status and takes part in no dependency graph, so
    /// this group carries no `--status` filter and no `deps` verb.
    Document {
        #[command(subcommand)]
        command: DocumentCommand,
    },

    /// List the labels the sources know.
    Label {
        #[command(subcommand)]
        command: LabelCommand,
    },

    /// Search tasks, projects, or both.
    Search(SearchArgs),

    /// Read a task template's variables, and render it from answers.
    ///
    /// A template is minijinja with YAML front matter declaring its variables. `extends`,
    /// `include` and `import` resolve over the --search-path directories alone.
    Template {
        #[command(subcommand)]
        command: TemplateCommand,
    },
}

/// What `onetaskgraph template` can do.
#[derive(Debug, Subcommand)]
pub enum TemplateCommand {
    /// List every variable a template's chain declares, and the chain's digest.
    Variables(TemplateVariablesArgs),
    /// Render a template from answers, asking for the rest when interactive.
    ///
    /// Each variable takes the first of: --var, the answers file, a prompt (when
    /// interactive), its default. Every refusal of an answer exits 2.
    Render(TemplateRenderArgs),
}

/// `onetaskgraph template variables`.
// llmlint: ignore-block[invalid_states_unrepresentable] clap's derive has no one-field spelling for mutually exclusive options, so the template's sources are separate optional fields; the ArgGroup and `conflicts_with` on them refuse any two together where they are typed (exit 2), and `template::input` converts them to the one `TemplateInput` enum before anything else reads them.
#[derive(Debug, Args)]
#[command(group = clap::ArgGroup::new("template_source").required(true).args(["file", "template_loader"]))]
pub struct TemplateVariablesArgs {
    /// The template to read, at a path. It is known to its chain, and in its digest, by its
    /// file name; its own directory is not searched unless it is also a --search-path.
    #[arg(value_name = "FILE")]
    pub file: Option<std::path::PathBuf>,

    /// Resolve `extends`, `include` and `import` names in this directory. Repeat for several,
    /// searched in order; the working directory is never searched unless it is named.
    #[arg(
        long = "search-path",
        value_name = "DIR",
        conflicts_with = "template_loader"
    )]
    pub search_path: Vec<std::path::PathBuf>,

    /// Read the template from a loader document in place of FILE: a JSON object naming its
    /// `entry`, the `search_path` and inline `templates` its chain resolves over, and a
    /// `reference`; `-` reads standard input.
    #[arg(long = "template-loader", value_name = "FILE")]
    pub template_loader: Option<std::path::PathBuf>,
}
// llmlint: ignore-end[invalid_states_unrepresentable]

/// `onetaskgraph template render`.
// llmlint: ignore-block[invalid_states_unrepresentable] clap's derive has no one-field spelling for mutually exclusive options, so the template's sources are separate optional fields; the ArgGroup and `conflicts_with` on them refuse any two together where they are typed (exit 2), and `template::input` converts them to the one `TemplateInput` enum before anything else reads them.
#[derive(Debug, Args)]
#[command(group = clap::ArgGroup::new("template_source").required(true).args(["file", "template_loader"]))]
pub struct TemplateRenderArgs {
    /// The template to read, at a path. It is known to its chain, and in its digest, by its
    /// file name; its own directory is not searched unless it is also a --search-path.
    #[arg(value_name = "FILE")]
    pub file: Option<std::path::PathBuf>,

    /// Resolve `extends`, `include` and `import` names in this directory. Repeat for several,
    /// searched in order; the working directory is never searched unless it is named.
    #[arg(
        long = "search-path",
        value_name = "DIR",
        conflicts_with = "template_loader"
    )]
    pub search_path: Vec<std::path::PathBuf>,

    /// Read the template from a loader document in place of FILE; `-` reads standard input.
    #[arg(long = "template-loader", value_name = "FILE")]
    pub template_loader: Option<std::path::PathBuf>,

    /// Read answers from this YAML file, a mapping from variable name to value; `-` reads
    /// standard input.
    #[arg(long, value_name = "FILE")]
    pub answers: Option<std::path::PathBuf>,

    /// Answer one variable, over the answers file: literal text for a `string` or `text`
    /// variable, YAML for any other type. Repeat for several.
    #[arg(
        long = "var",
        value_name = "NAME=VALUE",
        allow_hyphen_values = true,
        value_parser = var_assignment
    )]
    pub var: Vec<VarAssignment>,
}
// llmlint: ignore-end[invalid_states_unrepresentable]

/// One `--var NAME=VALUE`, split where it was typed.
///
/// The value stays text: whether it is taken literally or read as YAML is decided by the type
/// the template declares for `name`, which is not known until the template is loaded.
#[derive(Debug, Clone)]
pub struct VarAssignment {
    /// The variable answered: a name a variable could be declared with. Private, so the only
    /// way to build one is `var_assignment` below, which refuses any other name.
    name: String,
    /// The answer, as typed.
    value: String,
}

impl VarAssignment {
    /// The variable answered.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// The answer, as typed.
    pub fn value(&self) -> &str {
        &self.value
    }
}

/// Split one `--var` at its first `=`, refusing one with none, or whose name no variable
/// could be declared with.
fn var_assignment(raw: &str) -> Result<VarAssignment, String> {
    let (name, value) = raw.split_once('=').ok_or_else(|| {
        "that is not NAME=VALUE; next: write it as --var NAME=VALUE, for example \
         --var title=\"Ship it\""
            .to_owned()
    })?;
    if !onetaskgraph_core::template::is_variable_name(name) {
        return Err(format!(
            "{name:?} is not a variable name, which matches ^[a-z][a-z0-9_]*$; next: name a \
             variable the template declares — `onetaskgraph template variables` lists them"
        ));
    }
    Ok(VarAssignment {
        name: name.to_owned(),
        value: value.to_owned(),
    })
}

/// What `onetaskgraph sources` can do.
#[derive(Debug, Subcommand)]
pub enum SourcesCommand {
    /// List every configured source, its plugin, and what it declares it can do.
    ///
    /// A source that could not be built is listed too, with the reason — one broken
    /// credential is a source you can see is broken, not a command that stops working.
    List,
    /// Safely report or add configured GitHub Projects board Status options.
    ///
    /// The Status-only form of `sources fields`, which supersedes it. The default is a
    /// read-only plan. `--apply` preserves every existing option id and verifies every
    /// existing item assignment after GitHub replaces the option list.
    StatusOptions(SetupArgs),
    /// Safely report or set up every board field a GitHub Projects source's configuration
    /// names: its Status options, and its Priority field when `priority_mapping` is set.
    ///
    /// The default is a read-only plan. `--apply` adds missing options, creates a missing
    /// Priority field holding the mapped options, preserves every existing option's id,
    /// name, color and description, and verifies every item's values afterwards.
    Fields(SetupArgs),
    /// Say where an item written to a source would land, by that source's `routes`.
    ///
    /// Reads configuration alone, never a source: the destination is the source a route
    /// sends an item with these repositories to, or SOURCE itself when none matches.
    Route(RouteArgs),
}

/// `onetaskgraph sources route`.
#[derive(Debug, Args)]
pub struct RouteArgs {
    /// The configured source the item would be written to.
    // llmlint: ignore[invalid_states_unrepresentable] Clap collects this token as text so an unknown name is refused naming the configured ones; the command converts it to a `SourceName` before any lookup.
    pub source: String,
    /// One repository the item concerns, as a normalized origin `host/owner/name`. Repeat
    /// for several; none at all matches no route.
    #[arg(long = "repository", value_name = "R", value_parser = repository)]
    pub repository: Vec<Repository>,
    /// The item's classification: `public` (the default) or `private`. A private item is
    /// placed only where it may be written — a source declared private.
    #[arg(long = "classification", value_name = "CLASSIFICATION")]
    pub classification: Option<ClassificationArg>,
}

/// A repository origin as a command line hands one over.
fn repository(value: &str) -> Result<Repository, String> {
    Repository::try_from(value.to_owned())
}

/// Which configured source a guarded board setup inspects, and whether to apply its plan.
#[derive(Debug, Args)]
pub struct SetupArgs {
    /// The configured `github-projects` source name.
    // llmlint: ignore[invalid_states_unrepresentable] Clap collects this token as text;
    // the command converts it to `SourceName` before the configuration lookup or I/O.
    pub source: String,
    /// Add missing configured options and verify existing ids and assignments afterwards.
    #[arg(long)]
    // llmlint: ignore[invalid_states_unrepresentable] A presence-only CLI flag is
    // intrinsically boolean; the command immediately maps it to `SetupMode`.
    pub apply: bool,
}

/// What `onetaskgraph task` can do.
#[derive(Debug, Subcommand)]
pub enum TaskCommand {
    /// List tasks across the selected sources.
    List(TaskListArgs),
    /// Show one task by its qualified id, `<source>:<native-id>`.
    Show(TaskShowArgs),
    /// Show several tasks by their qualified ids, each as `task show` reports it.
    ///
    /// One detail per id, in the order given, and the ids may span sources. An id that cannot
    /// be read — no such task, a source nothing configures, comments a source refuses — says
    /// why in its own detail's `errors` and does not refuse the others; the command exits
    /// non-zero exactly when some detail carries an error. Each source is asked for its ids
    /// together, so a source that reads many items in one request answers in few.
    ShowMany(TaskShowManyArgs),
    /// Walk one task's dependency edges.
    Deps(DependencyArgs),
    /// Copy tasks into another configured source, by qualified id.
    Copy(TaskCopyArgs),
    /// Add, list, edit and delete one task's comments.
    ///
    /// A copy never reads or writes a comment, at either end: these verbs are the only way
    /// one is written.
    Comment {
        #[command(subcommand)]
        command: CommentCommand,
    },
    /// Set one task's status, and nothing else about it.
    ///
    /// Every task it delivers is kept in step with it afterwards, and each is reported.
    Status {
        #[command(subcommand)]
        command: StatusCommand,
    },
    /// Set one task's priority, and nothing else about it.
    ///
    /// Priority is not status: no task it delivers is re-evaluated.
    Priority {
        #[command(subcommand)]
        command: PriorityCommand,
    },
    /// Replace one task's content, and nothing else about it.
    ///
    /// Content is not status: no task it delivers is re-evaluated.
    Content {
        #[command(subcommand)]
        command: ContentCommand,
    },
    /// Set one key of one task's metadata, and nothing else about it.
    ///
    /// Metadata is not status: no task it delivers is re-evaluated.
    Metadata {
        #[command(subcommand)]
        command: MetadataCommand,
    },
    /// Update one task: every field named, and nothing else.
    ///
    /// A field already holding the value named is not written, and an update in which nothing
    /// differs writes nothing at all. Naming a status or a list of tasks it delivers keeps every
    /// task it delivers in step with it afterwards, and each is reported; naming neither
    /// re-evaluates nothing.
    Update(TaskUpdateArgs),
    /// Create a task in one source, its body rendered from a template or given as it is.
    ///
    /// Rendered from a template, it records where it came from under the reserved
    /// `onetaskgraph.template` metadata key, and a source that keeps an authoring file
    /// (local-md) stores the answers beside it for a later `task render`. An image its body
    /// references as `![alt](./<name>)` is stored with it from --asset.
    Create(TaskCreateArgs),
    /// Regenerate one task's content from its template in place, and nothing else about it.
    ///
    /// The answers start from the ones stored beside it when they are in step with its
    /// provenance; --var, --answers and --unset are laid over them. It keeps every stored
    /// image asset the new content still references, --asset replacing one by name.
    Render(ItemRenderArgs),
    /// Print the template answers stored beside one task.
    Answers(AnswersArgs),
}

/// Where a created item's body comes from: exactly one of a template file, a loader
/// document, a body file, or — with none of them — standard input.
// llmlint: ignore-block[invalid_states_unrepresentable] clap's derive has no one-field spelling for mutually exclusive options, so the template's sources are separate optional fields; the ArgGroup and `conflicts_with` on them refuse any two together where they are typed (exit 2), and `template::input` converts them to the one `TemplateInput` enum before anything else reads them.
#[derive(Debug, Args)]
pub struct CreateBodyArgs {
    /// Render the body from this template file, recorded by its absolute path.
    #[arg(long, value_name = "FILE", conflicts_with_all = ["template_loader", "body_file"])]
    pub template: Option<std::path::PathBuf>,

    /// Resolve the template's `extends`, `include` and `import` names in this directory.
    /// Repeat for several.
    #[arg(long = "search-path", value_name = "DIR", requires = "template")]
    pub search_path: Vec<std::path::PathBuf>,

    /// Render the body from the template a loader document states, recorded by its
    /// `reference`; `-` reads standard input.
    #[arg(
        long = "template-loader",
        value_name = "FILE",
        conflicts_with = "body_file"
    )]
    pub template_loader: Option<std::path::PathBuf>,

    /// Read the template's answers from this YAML file; `-` reads standard input.
    #[arg(long, value_name = "FILE", requires = "rendered")]
    pub answers: Option<std::path::PathBuf>,

    /// Answer one template variable, over the answers file. Repeat for several.
    #[arg(
        long = "var",
        value_name = "NAME=VALUE",
        allow_hyphen_values = true,
        value_parser = var_assignment,
        requires = "rendered"
    )]
    pub var: Vec<VarAssignment>,

    /// Read the body from this file, byte for byte, rather than rendering it.
    #[arg(long = "body-file", value_name = "PATH")]
    pub body_file: Option<std::path::PathBuf>,
}
// llmlint: ignore-end[invalid_states_unrepresentable]

/// What every create names about the item besides its body.
#[derive(Debug, Args)]
pub struct CreateItemArgs {
    /// The configured source to create it in.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `CopyArgs::to`: `main` converts
    /// it through `SourceName::new` with the next action a user needs.
    #[arg(value_name = "SOURCE")]
    pub source: String,

    /// The project to file it under, by the source's own id (or qualified with that source).
    #[arg(long, value_name = "P")]
    pub project: String,

    /// Its title.
    #[arg(long, value_name = "TITLE")]
    pub title: String,

    /// Give it this label. Repeat for several.
    #[arg(long = "label", value_name = "L")]
    pub label: Vec<String>,

    /// A repository its work changes, as a normalized origin (`github.com/owner/name`). Repeat
    /// for several.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — `main` converts each through the
    /// contract's own `Repository` and refuses one naming the problem.
    #[arg(long = "repository", value_name = "R")]
    pub repository: Vec<String>,

    /// Set one caller-owned metadata key to one JSON value. Repeat for several; a key in the
    /// reserved `onetaskgraph.` namespace is refused.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `MetadataSetArgs::key`: `main`
    /// converts each through `MetadataKey::new` and parses its value as JSON before anything
    /// is built.
    #[arg(long = "metadata", value_name = "KEY=JSON", allow_hyphen_values = true)]
    pub metadata: Vec<String>,

    /// Who may read it: `public` or `private`. Its repositories and its project tighten it,
    /// and nothing loosens it — a project already private stays private.
    #[arg(long = "classification", value_name = "CLASSIFICATION")]
    pub classification: Option<ClassificationArg>,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,

    #[command(flatten)]
    pub body: CreateBodyArgs,
}

/// `onetaskgraph task create`.
#[derive(Debug, Args)]
#[command(group = clap::ArgGroup::new("rendered").args(["template", "template_loader"]).multiple(false))]
pub struct TaskCreateArgs {
    #[command(flatten)]
    pub item: CreateItemArgs,

    /// Its status category; `todo` when none is given.
    #[arg(long = "status", value_name = "CATEGORY")]
    pub status: Option<StatusArg>,

    /// A task it depends on, qualified (`work:T-1`). Repeat for several.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `ShowArgs::id`.
    #[arg(long = "depends-on", value_name = "ID")]
    pub depends_on: Vec<String>,

    /// A task it delivers, qualified. Repeat for several; each is kept in step with it.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `ShowArgs::id`.
    #[arg(long = "delivers", value_name = "ID")]
    pub delivers: Vec<String>,

    #[command(flatten)]
    pub assets: AssetArgs,
}

/// The image assets a create or a render stores with a task or a document.
#[derive(Debug, Args)]
pub struct AssetArgs {
    /// Store this image with it, under the file's base name, which its content references as
    /// `![alt](./<name>)`. Repeat for several; each must end in .png, .jpg, .jpeg, .gif or
    /// .webp, and be referenced.
    #[arg(long = "asset", value_name = "PATH")]
    pub asset: Vec<std::path::PathBuf>,
}

/// `onetaskgraph task render` and `onetaskgraph document render`: what every render names, and
/// the image assets to store with the item.
#[derive(Debug, Args)]
pub struct ItemRenderArgs {
    #[command(flatten)]
    pub render: RenderArgs,

    #[command(flatten)]
    pub assets: AssetArgs,
}

/// `onetaskgraph document create`.
#[derive(Debug, Args)]
#[command(group = clap::ArgGroup::new("rendered").args(["template", "template_loader"]).multiple(false))]
pub struct DocumentCreateArgs {
    #[command(flatten)]
    pub item: CreateItemArgs,

    /// Write it under this id: a document the source holds by it is replaced, and otherwise
    /// one is created under it.
    #[arg(long = "id", value_name = "DOC", value_parser = native_id)]
    pub id: Option<NativeId>,

    #[command(flatten)]
    pub assets: AssetArgs,
}

/// `onetaskgraph project create`.
///
/// What `document create` names about an item, less the project it is filed under — a project
/// is filed under none — with the id it is written under required, and a status.
#[derive(Debug, Args)]
#[command(group = clap::ArgGroup::new("rendered").args(["template", "template_loader"]).multiple(false))]
pub struct ProjectCreateArgs {
    /// The configured source to create it in.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `CopyArgs::to`: `main` converts
    /// it through `SourceName::new` with the next action a user needs.
    #[arg(value_name = "SOURCE")]
    pub source: String,

    /// Write it under this id: a project the source holds by it is replaced, and otherwise
    /// one is created under it.
    #[arg(long = "id", value_name = "NATIVE-ID", value_parser = native_id)]
    pub id: NativeId,

    /// Its title.
    #[arg(long, value_name = "TITLE")]
    pub title: String,

    /// Its status category: `todo` for a new project when none is given, and the status it
    /// holds for one being replaced.
    #[arg(long = "status", value_name = "CATEGORY")]
    pub status: Option<StatusArg>,

    /// Give it this label. Repeat for several; given, they replace the labels a project being
    /// replaced holds.
    #[arg(long = "label", value_name = "L")]
    pub label: Vec<String>,

    /// A repository it concerns, as a normalized origin (`github.com/owner/name`). Repeat for
    /// several; given, they replace the repositories a project being replaced holds.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — `main` converts each through the
    /// contract's own `Repository` and refuses one naming the problem.
    #[arg(long = "repository", value_name = "R")]
    pub repository: Vec<String>,

    /// Set one caller-owned metadata key to one JSON value. Repeat for several; a key in the
    /// reserved `onetaskgraph.` namespace is refused, and every other key a project being
    /// replaced holds is kept.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `MetadataSetArgs::key`: `main`
    /// converts each through `MetadataKey::new` and parses its value as JSON before anything
    /// is built.
    #[arg(long = "metadata", value_name = "KEY=JSON", allow_hyphen_values = true)]
    pub metadata: Vec<String>,

    /// Who may read it: `public` or `private`. Its repositories and its project tighten it,
    /// and nothing loosens it — a project already private stays private.
    #[arg(long = "classification", value_name = "CLASSIFICATION")]
    pub classification: Option<ClassificationArg>,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,

    #[command(flatten)]
    pub body: CreateBodyArgs,
}

/// `onetaskgraph task render`, `onetaskgraph project render` and `onetaskgraph document render`.
// llmlint: ignore-block[invalid_states_unrepresentable] clap's derive has no one-field spelling for mutually exclusive options, so the template's sources are separate optional fields; the ArgGroup and `conflicts_with` on them refuse any two together where they are typed (exit 2), and `template::input` converts them to the one `TemplateInput` enum before anything else reads them.
#[derive(Debug, Args)]
pub struct RenderArgs {
    /// The item's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `ShowArgs::id`.
    #[arg(value_name = "ID")]
    pub id: String,

    /// Render this template file rather than the one the item records.
    #[arg(long, value_name = "FILE", conflicts_with = "template_loader")]
    pub template: Option<std::path::PathBuf>,

    /// Resolve the template's `extends`, `include` and `import` names in this directory —
    /// the given template's, or the recorded file's. Repeat for several.
    #[arg(
        long = "search-path",
        value_name = "DIR",
        conflicts_with = "template_loader"
    )]
    pub search_path: Vec<std::path::PathBuf>,

    /// Render the template a loader document states, which a recorded reference that is not
    /// a readable file requires; `-` reads standard input.
    #[arg(long = "template-loader", value_name = "FILE")]
    pub template_loader: Option<std::path::PathBuf>,

    /// Read answers from this YAML file, laid over the base; `-` reads standard input.
    #[arg(long, value_name = "FILE")]
    pub answers: Option<std::path::PathBuf>,

    /// Answer one variable, over the answers file. Repeat for several.
    #[arg(
        long = "var",
        value_name = "NAME=VALUE",
        allow_hyphen_values = true,
        value_parser = var_assignment
    )]
    pub var: Vec<VarAssignment>,

    /// Drop the answer this variable held, so it takes its default. Repeat for several.
    #[arg(long = "unset", value_name = "NAME", value_parser = variable_name)]
    pub unset: Vec<String>,

    /// Render and report, and write nothing.
    #[arg(long = "dry-run")]
    pub dry_run: bool,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}
// llmlint: ignore-end[invalid_states_unrepresentable]

/// `onetaskgraph task answers`, `onetaskgraph project answers` and
/// `onetaskgraph document answers`.
#[derive(Debug, Args)]
pub struct AnswersArgs {
    /// The item's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `ShowArgs::id`.
    #[arg(value_name = "ID")]
    pub id: String,
}

/// One `--unset NAME`, refused unless a variable could be declared with it.
fn variable_name(raw: &str) -> Result<String, String> {
    if onetaskgraph_core::template::is_variable_name(raw) {
        Ok(raw.to_owned())
    } else {
        Err(format!(
            "{raw:?} is not a variable name, which matches ^[a-z][a-z0-9_]*$; next: name a \
             variable the template declares — `onetaskgraph template variables` lists them"
        ))
    }
}

/// `onetaskgraph task update`.
///
/// Every flag names one field of the task, and at least one is required — refused by
/// `update::update_task` rather than by a required group, which would spell every flag into the
/// usage line. A list flag given once or more replaces that list whole; its `--no-…` twin
/// replaces it with none.
// llmlint: ignore-block[invalid_states_unrepresentable] clap's derive has no one-field spelling for "a list, or explicitly none, or not named", so each replaceable list is a repeated option beside a `--no-…` flag; `conflicts_with` refuses the two together where they are typed (exit 2), and `update::request` folds each pair into the contract's own `Option<Vec<_>>` before anything else reads them.
#[derive(Debug, Args)]
pub struct TaskUpdateArgs {
    /// The task's qualified id, `<source>:<native-id>`.
    #[arg(value_name = "ID")]
    pub id: String,

    /// Its title.
    #[arg(long, value_name = "TITLE")]
    pub title: Option<String>,

    /// Replace its content with this file's bytes.
    #[arg(long = "body-file", value_name = "PATH")]
    pub body_file: Option<std::path::PathBuf>,

    /// Its status category.
    #[arg(long = "status", value_name = "CATEGORY")]
    pub status: Option<StatusArg>,

    /// The status's own word, where the source keeps one — a folder of Markdown writes it as
    /// it is, and a source mapping statuses by category writes the category's option. The
    /// category's own word when left out.
    #[arg(long = "status-name", value_name = "NAME", requires = "status")]
    pub status_name: Option<String>,

    /// Its priority; `none` clears it.
    #[arg(long = "priority", value_name = "PRIORITY")]
    pub priority: Option<PriorityArg>,

    /// Set one caller-owned metadata key to one JSON value. Repeat for several; every other
    /// key is kept.
    #[arg(long = "metadata", value_name = "KEY=JSON", allow_hyphen_values = true)]
    pub metadata: Vec<String>,

    /// Remove one caller-owned metadata key. Repeat for several; a key the task does not hold
    /// is no write.
    #[arg(long = "remove-metadata", value_name = "KEY")]
    pub remove_metadata: Vec<String>,

    /// A task it delivers, qualified. Repeat for several; together they replace the list.
    #[arg(long = "delivers", value_name = "ID", conflicts_with = "no_delivers")]
    pub delivers: Vec<String>,

    /// Replace the list of tasks it delivers with none.
    #[arg(long = "no-delivers")]
    pub no_delivers: bool,

    /// A task it depends on, qualified. Repeat for several; together they replace its
    /// dependencies.
    #[arg(
        long = "depends-on",
        value_name = "ID",
        conflicts_with = "no_depends_on"
    )]
    pub depends_on: Vec<String>,

    /// Replace its dependencies with none.
    #[arg(long = "no-depends-on")]
    pub no_depends_on: bool,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}
// llmlint: ignore-end[invalid_states_unrepresentable]

/// What `onetaskgraph task priority` can do.
#[derive(Debug, Subcommand)]
pub enum PriorityCommand {
    /// Set one task's priority, and nothing else about it; `none` clears it.
    Set(PrioritySetArgs),
}

/// `onetaskgraph task priority set`.
#[derive(Debug, Args)]
pub struct PrioritySetArgs {
    /// The task's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `StatusSetArgs::id`: a `GlobalId`
    /// here would refuse an unqualified id as a bad invocation under clap's wording, and
    /// `qualified` in `main` converts it immediately with the next action a user needs.
    #[arg(value_name = "ID")]
    pub id: String,

    /// The priority to set.
    #[arg(value_name = "PRIORITY")]
    pub priority: PriorityArg,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}

/// What `onetaskgraph task content` can do.
#[derive(Debug, Subcommand)]
pub enum ContentCommand {
    /// Replace one task's content with a file's bytes, and nothing else about it.
    ///
    /// Status, priority, metadata, labels, repositories and dependencies are left as they
    /// were. There is no compare-and-set: the file's bytes replace whatever the task holds.
    Set(ContentSetArgs),
}

/// `onetaskgraph task content set`.
#[derive(Debug, Args)]
pub struct ContentSetArgs {
    /// The task's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `StatusSetArgs::id`.
    #[arg(value_name = "ID")]
    pub id: String,

    /// Read the new content from this file, byte for byte.
    #[arg(long, value_name = "PATH")]
    pub file: std::path::PathBuf,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}

/// What `onetaskgraph task metadata`, `project metadata` and `document metadata` can do.
#[derive(Debug, Subcommand)]
pub enum MetadataCommand {
    /// Set one metadata key to one JSON value, adding the key or replacing what it holds.
    ///
    /// Every other key, and every other field of the record, is left as it was; a key already
    /// holding the value is not written at all.
    Set(MetadataSetArgs),
}

/// `onetaskgraph <task|project|document> metadata set`.
#[derive(Debug, Args)]
pub struct MetadataSetArgs {
    /// The record's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `StatusSetArgs::id`: a `GlobalId`
    /// here would refuse an unqualified id as a bad invocation under clap's wording, and
    /// `qualified` in `main` converts it immediately with the next action a user needs.
    #[arg(value_name = "ID")]
    pub id: String,

    /// The key, `<namespace>.<name>`: two or more non-empty dot-separated segments, never in
    /// the `onetaskgraph.` namespace.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `id` above: `metadata_key` in
    /// `main` converts it through `MetadataKey::new` before anything is built, and a clap
    /// value parser would report the same refusal as a bad invocation without its next action.
    #[arg(value_name = "KEY")]
    pub key: String,

    /// The value, as exactly one JSON value: `null`, `true`, `3`, `"text"`, `[…]` or `{…}`.
    ///
    /// Parsed strictly as JSON and never as YAML, so a bare word such as `yes` or a date such
    /// as `2026-01-01` is refused rather than silently given a type; quote a string.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `key` above: `metadata_value` in
    /// `main` parses it before anything is built, naming the parse error and the next action.
    #[arg(value_name = "VALUE", allow_hyphen_values = true)]
    pub value: String,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}

/// What `onetaskgraph task status` can do.
#[derive(Debug, Subcommand)]
pub enum StatusCommand {
    /// Set one task's status to a category, and nothing else about it.
    Set(StatusSetArgs),
}

/// `onetaskgraph task status set`.
#[derive(Debug, Args)]
pub struct StatusSetArgs {
    /// The task's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `CommentAddArgs::id`: a `GlobalId`
    /// here would refuse an unqualified id as a bad invocation under clap's wording, and
    /// `qualified` in `main` converts it immediately with the next action a user needs.
    #[arg(value_name = "ID")]
    pub id: String,

    /// The status category to set.
    #[arg(value_name = "CATEGORY")]
    pub category: StatusArg,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}

/// What `onetaskgraph task comment` can do.
///
/// A body is read from `--body-file`, or from standard input when that flag is absent, and
/// never from a word of the command line: a comment quoting a command must not pass through
/// a shell to reach the source.
#[derive(Debug, Subcommand)]
pub enum CommentCommand {
    /// Add a comment to a task. The body comes from --body-file, or from standard input.
    Add(CommentAddArgs),
    /// List a task's comments, oldest first.
    List(CommentListArgs),
    /// Replace one comment's body. The body comes from --body-file, or from standard input.
    Edit(CommentEditArgs),
    /// Delete one comment from a task.
    Delete(CommentDeleteArgs),
}

/// `onetaskgraph task comment add`.
#[derive(Debug, Args)]
pub struct CommentAddArgs {
    /// The task's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `ShowArgs::id`: a `GlobalId`
    /// here would refuse an unqualified id as a bad invocation under clap's wording, and
    /// `qualified` in `main` converts it immediately with the next action a user needs.
    #[arg(value_name = "ID")]
    pub id: String,

    /// Read the body from this file rather than from standard input, byte for byte.
    #[arg(long = "body-file", value_name = "PATH")]
    pub body_file: Option<std::path::PathBuf>,

    /// Who wrote it. A source that records the author itself refuses this, saying why.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — an author is each source's own
    /// spelling of a person, so there is no narrower type every source agrees on; the
    /// source refuses what it cannot record, naming why, as `NewComment::author` records.
    #[arg(long, value_name = "NAME")]
    pub author: Option<String>,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}

/// `onetaskgraph task comment list`.
#[derive(Debug, Args)]
pub struct CommentListArgs {
    /// The task's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `CommentAddArgs::id`.
    #[arg(value_name = "ID")]
    pub id: String,
}

/// `onetaskgraph task comment edit`.
#[derive(Debug, Args)]
pub struct CommentEditArgs {
    /// The task's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `CommentAddArgs::id`.
    #[arg(value_name = "ID")]
    pub id: String,

    /// The comment's own id, exactly as `list` or `add` reported it.
    #[arg(value_name = "COMMENT-ID", value_parser = native_id)]
    pub comment_id: NativeId,

    /// Read the new body from this file rather than from standard input, byte for byte.
    #[arg(long = "body-file", value_name = "PATH")]
    pub body_file: Option<std::path::PathBuf>,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}

/// `onetaskgraph task comment delete`.
#[derive(Debug, Args)]
pub struct CommentDeleteArgs {
    /// The task's qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `CommentAddArgs::id`.
    #[arg(value_name = "ID")]
    pub id: String,

    /// The comment's own id, exactly as `list` or `add` reported it.
    #[arg(value_name = "COMMENT-ID", value_parser = native_id)]
    pub comment_id: NativeId,
}

/// A source's own id, as a command line hands one over.
///
/// Never refused: a native id is whatever its source issued, so the one thing this does is
/// give the value the contract's own type where it enters.
fn native_id(value: &str) -> Result<NativeId, std::convert::Infallible> {
    Ok(NativeId::from(value))
}

/// What `onetaskgraph project` can do.
#[derive(Debug, Subcommand)]
pub enum ProjectCommand {
    /// List projects across the selected sources.
    List(ProjectListArgs),
    /// Show one project by its qualified id, `<source>:<native-id>`.
    Show(ShowArgs),
    /// Walk one project's dependency edges.
    Deps(DependencyArgs),
    /// Print one project's tasks and their dependency edges as Mermaid flowchart text, or
    /// as the JSON document that describes the same graph.
    ///
    /// It draws nothing itself: hand the text to whatever renders Mermaid.
    #[command(after_long_help = GRAPH_CONTRACT)]
    Graph(GraphArgs),
    /// Copy one project, and the tasks in it, into another configured source.
    Copy(ProjectCopyArgs),
    /// Set one key of one project's metadata, and nothing else about it.
    Metadata {
        #[command(subcommand)]
        command: MetadataCommand,
    },
    /// Create — or, with --id naming one it holds, replace — a project, its description
    /// rendered from a template or given as it is.
    ///
    /// Rendered from a template, it records where it came from under the reserved
    /// `onetaskgraph.template` metadata key, and a source that keeps an authoring file
    /// (local-md) stores the answers beside it for a later `project render`. Replacing a
    /// project replaces its content, answers and provenance whole, and keeps its metadata,
    /// status, labels and repositories but for what is named here.
    Create(ProjectCreateArgs),
    /// Regenerate one project's description from its template in place, and nothing else
    /// about it.
    ///
    /// The answers start from the ones stored beside it when they are in step with its
    /// provenance; --var, --answers and --unset are laid over them.
    Render(RenderArgs),
    /// Print the template answers stored beside one project.
    Answers(AnswersArgs),
}

/// What `onetaskgraph document` can do.
///
/// No `deps`: a document takes part in no dependency graph, so there is nothing for a
/// dependency verb here to walk.
#[derive(Debug, Subcommand)]
pub enum DocumentCommand {
    /// List documents across the selected sources.
    List(DocumentListArgs),
    /// Show one document by its qualified id, `<source>:<native-id>`.
    Show(ShowArgs),
    /// Copy documents into another configured source, by qualified id.
    Copy(DocumentCopyArgs),
    /// Set one key of one document's metadata, and nothing else about it.
    Metadata {
        #[command(subcommand)]
        command: MetadataCommand,
    },
    /// Create — or, with --id naming one it holds, replace — a project document, its body
    /// rendered from a template or given as it is.
    ///
    /// An image its body references as `![alt](./<name>)` is stored with it from --asset; a
    /// document replaced holds exactly the assets this names.
    Create(DocumentCreateArgs),
    /// Regenerate one document's content from its template in place, and nothing else about
    /// it.
    ///
    /// It keeps every stored image asset the new content still references, --asset replacing
    /// one by name.
    Render(ItemRenderArgs),
    /// Print the template answers stored beside one document.
    Answers(AnswersArgs),
}

/// What `onetaskgraph label` can do.
#[derive(Debug, Subcommand)]
pub enum LabelCommand {
    /// List every label the selected sources know.
    List(LabelListArgs),
}

/// Which sources a query addresses.
#[derive(Debug, Args)]
pub struct SelectionArgs {
    /// Address this source. Repeat for several; omit for the configured selection.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — a `SourceName` here would move
    /// the refusal into clap, which reports it as an invalid *invocation* (exit 2) under
    /// clap's own wording. A name that cannot be a source name and one that names no
    /// configured source are the same typo to the user, and both owe the same next
    /// action; `selection` in `main` converts through `SourceName::new` immediately and
    /// attaches it, at the exit code the documented table gives that mistake.
    #[arg(long = "source", value_name = "S")]
    pub source: Vec<String>,
}

/// The filters the list verbs share.
#[derive(Debug, Args)]
pub struct FilterArgs {
    /// Keep items carrying this label. Repeat to require several at once.
    #[arg(long = "label", value_name = "L")]
    pub label: Vec<String>,

    /// Drop items carrying this label. Repeat for several.
    #[arg(long = "not-label", value_name = "L")]
    pub not_label: Vec<String>,

    /// Keep items in this status category. Repeat for several.
    #[arg(long = "status", value_name = "S")]
    pub status: Vec<StatusArg>,

    /// Keep items matching this text.
    #[arg(long, value_name = "TEXT")]
    pub search: Option<String>,

    /// Which fields --search looks in.
    #[arg(long = "in", value_name = "FIELDS", default_value = "both")]
    pub fields: FieldsArg,
}

/// The filters a document list carries.
///
/// [`FilterArgs`] without `--status`, and its own type rather than a shared one for the
/// reason [`DocumentFilters`](onetaskgraph_core::DocumentFilters) is: a document has no
/// status, so a status flag here could only be accepted and ignored.
#[derive(Debug, Args)]
pub struct DocumentFilterArgs {
    /// Keep documents carrying this label. Repeat to require several at once.
    #[arg(long = "label", value_name = "L")]
    pub label: Vec<String>,

    /// Drop documents carrying this label. Repeat for several.
    #[arg(long = "not-label", value_name = "L")]
    pub not_label: Vec<String>,

    /// Keep documents matching this text.
    #[arg(long, value_name = "TEXT")]
    pub search: Option<String>,

    /// Which fields --search looks in.
    #[arg(long = "in", value_name = "FIELDS", default_value = "both")]
    pub fields: FieldsArg,
}

/// How much of a result set to return, and how much to say about it.
#[derive(Debug, Args)]
pub struct PageArgs {
    /// How many items this page holds. Defaults to the `page_size` setting.
    ///
    /// A `NonZeroU32` rather than a range-checked `u32`: a page of no rows is not a page,
    /// and typing it should be refused where it was typed rather than carried inwards as
    /// a number some later layer has to remember to check.
    #[arg(long, value_name = "N")]
    pub limit: Option<NonZeroU32>,

    /// Resume from a token a previous page reported.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — a `PageToken` here would only
    /// move the *encoding* check to parse time, and a token is refused for three reasons
    /// beyond its encoding — a configuration it cannot address, a query it did not come
    /// from, a stream it does not resume — none of which is decidable before the
    /// configuration is loaded. Splitting one mistake ("I pasted the wrong token") across
    /// clap's exit 2 and the run's exit 1 is what that would buy.
    #[arg(long = "page", value_name = "TOKEN")]
    pub page: Option<String>,

    /// Report what each source was asked and what the engine did itself.
    #[arg(long)]
    pub explain: bool,

    /// Accept an answer some sources could not contribute to, and exit 0.
    #[arg(long = "allow-partial")]
    pub allow_partial: bool,
}

/// `onetaskgraph task list`.
#[derive(Debug, Args)]
pub struct TaskListArgs {
    #[command(flatten)]
    pub selection: SelectionArgs,

    #[command(flatten)]
    pub filters: FilterArgs,

    /// Keep tasks in this project, qualified (`work:PROJ-1`) or by native id.
    ///
    /// A qualified id names one project of one source, so it narrows the query to that
    /// source. A bare id is asked of every selected source.
    #[arg(long, value_name = "P", conflicts_with = "no_project")]
    pub project: Option<String>,

    /// Keep only tasks belonging to no project at all.
    #[arg(long = "no-project")]
    pub no_project: bool,

    /// With a qualified --project, read the tasks of every member project it names in
    /// other sources as well, each under its own source.
    #[arg(long = "members", requires = "project")]
    // llmlint: ignore[invalid_states_unrepresentable] A presence-only CLI flag is
    // intrinsically boolean; it maps straight onto `TaskRequest::include_members`.
    pub members: bool,

    /// Keep tasks with this priority. Repeat for several; a task matching any one is kept.
    #[arg(long = "priority", value_name = "PRIORITY")]
    pub priority: Vec<PriorityArg>,

    /// Keep tasks with a comment created or last edited at or after this RFC 3339 instant,
    /// offset included (`2026-09-28T12:00:00Z`). A task with no comments is never kept.
    ///
    /// A source that does not apply this itself has its comments read task by task.
    #[arg(long = "commented-since", value_name = "RFC3339", value_parser = instant)]
    pub commented_since: Option<DateTime<Utc>>,

    /// Keep tasks holding this metadata value: `<KEY>[/<SEGMENT>…]=<VALUE>`. Repeat for
    /// several; a task is kept when it holds every one.
    ///
    /// `/` splits the top-level key — which may contain dots, such as
    /// `orchestrator.follow-up` — from nested object keys under it, and the first `=` splits
    /// that location from the value. The value there must be a JSON string equal to VALUE,
    /// case-sensitively: `--metadata orchestrator.follow-up/root_cause=stale-cache`.
    #[arg(long = "metadata", value_name = "KEY[/SEGMENT...]=VALUE", value_parser = metadata_match)]
    pub metadata: Vec<MetadataMatch>,

    /// Keep tasks copied from this item: those whose recorded copy origin is exactly this
    /// qualified id, `<source>:<native-id>`.
    #[arg(long = "origin", value_name = "SOURCE:ID", value_parser = origin)]
    pub origin: Option<GlobalId>,

    #[command(flatten)]
    pub paging: PageArgs,
}

/// A metadata match as a command line hands one over: `<KEY>[/<SEGMENT>…]=<VALUE>`.
///
/// The first `=` ends the location, so a value may hold `=` and `/` freely; a key or a
/// segment may hold neither. An empty key or an empty segment names no location, so it is
/// refused rather than read as one.
fn metadata_match(value: &str) -> Result<MetadataMatch, String> {
    let Some((location, wanted)) = value.split_once('=') else {
        return Err("no `=`; expected <KEY>[/<SEGMENT>...]=<VALUE>, such as \
             orchestrator.follow-up/root_cause=stale-cache"
            .to_owned());
    };
    let mut segments = location.split('/').map(str::to_owned);
    let key = segments.next().unwrap_or_default();
    MetadataMatch::new(key, segments.collect(), wanted).map_err(|refused| {
        format!(
            "{refused}; expected <KEY>[/<SEGMENT>...]=<VALUE>, such as \
             orchestrator.follow-up/root_cause=stale-cache"
        )
    })
}

/// A copy origin as a command line hands one over: a qualified id, refused before any
/// source is asked when it is not one.
fn origin(value: &str) -> Result<GlobalId, String> {
    GlobalId::from_str(value).map_err(|error| error.to_string())
}

/// An instant as a command line hands one over: RFC 3339, with its offset.
///
/// An instant with no offset names a different moment in every time zone, so it is refused
/// rather than read as UTC or as local time.
fn instant(value: &str) -> Result<DateTime<Utc>, String> {
    DateTime::parse_from_rfc3339(value)
        .map(|parsed| parsed.with_timezone(&Utc))
        .map_err(|error| {
            format!(
                "{error}; expected an RFC 3339 instant with its offset, such as \
                 2026-09-28T12:00:00Z or 2026-09-28T08:00:00-04:00"
            )
        })
}

/// `onetaskgraph project list`.
#[derive(Debug, Args)]
pub struct ProjectListArgs {
    #[command(flatten)]
    pub selection: SelectionArgs,

    #[command(flatten)]
    pub filters: FilterArgs,

    #[command(flatten)]
    pub paging: PageArgs,
}

/// `onetaskgraph document list`.
#[derive(Debug, Args)]
pub struct DocumentListArgs {
    #[command(flatten)]
    pub selection: SelectionArgs,

    #[command(flatten)]
    pub filters: DocumentFilterArgs,

    /// Keep documents in this project, qualified (`work:PROJ-1`) or by native id.
    ///
    /// A qualified id names one project of one source, so it narrows the query to that
    /// source. A bare id is asked of every selected source.
    #[arg(long, value_name = "P", conflicts_with = "no_project")]
    pub project: Option<String>,

    /// Keep only documents belonging to no project at all.
    #[arg(long = "no-project")]
    pub no_project: bool,

    #[command(flatten)]
    pub paging: PageArgs,
}

/// `onetaskgraph label list`.
#[derive(Debug, Args)]
pub struct LabelListArgs {
    #[command(flatten)]
    pub selection: SelectionArgs,

    #[command(flatten)]
    pub paging: PageArgs,
}

/// `onetaskgraph task show`, optionally reading only the record.
#[derive(Debug, Args)]
pub struct TaskShowArgs {
    #[command(flatten)]
    pub item: ShowArgs,
    /// Read the record without requesting its comments.
    #[arg(long)]
    pub no_comments: bool,
}

/// `onetaskgraph task show-many`.
#[derive(Debug, Args)]
pub struct TaskShowManyArgs {
    // llmlint: ignore-block[invalid_states_unrepresentable] As `TaskCopyArgs::id`: a `GlobalId` here would refuse an unqualified id as a bad invocation under clap's wording, and `qualified` in `main` converts each through `GlobalId::from_str` before any source is started, saying what a qualified id is and where to read the configured names.
    /// The qualified ids, `<source>:<native-id>`, in the order their details are reported.
    #[arg(value_name = "ID", required = true)]
    pub ids: Vec<String>,
    // llmlint: ignore-end[invalid_states_unrepresentable]
    /// Read each record without requesting its comments.
    #[arg(long)]
    pub no_comments: bool,
}

/// `onetaskgraph task show` and `onetaskgraph project show`.
#[derive(Debug, Args)]
pub struct ShowArgs {
    /// The qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — a `GlobalId` here would refuse an
    /// unqualified id as a bad invocation, under clap's wording. `qualified` in `main`
    /// converts through `GlobalId::from_str` immediately and says what a qualified id is
    /// and where to read the configured names, which is the answer a user typing `T-1`
    /// needs and the one this repository's failure journeys assert on.
    #[arg(value_name = "ID")]
    pub id: String,

    /// Report what the source was asked.
    #[arg(long)]
    pub explain: bool,

    /// Accept an answer the source could not contribute to, and exit 0.
    #[arg(long = "allow-partial")]
    pub allow_partial: bool,
}

/// `onetaskgraph task deps` and `onetaskgraph project deps`.
#[derive(Debug, Args)]
pub struct DependencyArgs {
    /// The qualified id, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — a `GlobalId` here would refuse an
    /// unqualified id as a bad invocation, under clap's wording. `qualified` in `main`
    /// converts through `GlobalId::from_str` immediately and says what a qualified id is
    /// and where to read the configured names, which is the answer a user typing `T-1`
    /// needs and the one this repository's failure journeys assert on.
    #[arg(value_name = "ID")]
    pub id: String,

    /// Which way to walk. Reverse is emulated for a forward-only source.
    #[arg(long, value_name = "DIRECTION", default_value = "depends-on")]
    pub direction: DirectionArg,

    #[command(flatten)]
    pub paging: PageArgs,
}

/// `onetaskgraph project graph`.
#[derive(Debug, Args)]
pub struct GraphArgs {
    /// The project's qualified id, `<source>:<native-id>`.
    #[arg(value_name = "ID")]
    // llmlint: ignore[invalid_states_unrepresentable] As `DependencyArgs::id`: a `GlobalId` here would refuse an unqualified id as a bad invocation, exit 2, in clap's words, where `qualified` in `main` converts it through `GlobalId::from_str` immediately and refuses it as `project show` and `project deps` refuse theirs — and `graph::an_empty_project_a_long_one_and_an_unknown_one` holds the graph's refusal to be `project show`'s, byte for byte.
    pub id: String,

    /// Which form to print.
    #[arg(long, value_name = "FORMAT", default_value = "mermaid")]
    pub format: GraphFormat,

    /// Which way to lay the graph out.
    #[arg(long, value_name = "DIRECTION", default_value = "auto")]
    pub direction: GraphDirectionArg,

    /// Group the project's tasks by the non-empty string each holds under this metadata key.
    #[arg(long = "group-by", value_name = "KEY", value_parser = group_key)]
    pub group_by: Option<onetaskgraph_core::GroupKey>,
}

/// A `--group-by` key, refused when it is empty: an empty key names no metadata at all.
fn group_key(value: &str) -> Result<onetaskgraph_core::GroupKey, String> {
    onetaskgraph_core::GroupKey::new(value)
}

/// The two forms `project graph` prints.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum GraphFormat {
    /// Mermaid flowchart text, for a renderer.
    Mermaid,
    /// The JSON document describing the same graph, keyed by task id, for a program.
    Json,
}

/// Which way `project graph` lays the graph out, as the command line spells it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum GraphDirectionArg {
    /// Left to right when the widest rank holds more tasks than there are ranks; top-down
    /// otherwise.
    Auto,
    /// Top-down: `flowchart TD`.
    Td,
    /// Left to right: `flowchart LR`.
    Lr,
}

impl GraphDirectionArg {
    /// The direction asked for, or `None` for `auto`, which the engine resolves.
    #[must_use]
    pub const fn direction(self) -> Option<onetaskgraph_core::GraphDirection> {
        match self {
            Self::Auto => None,
            Self::Td => Some(onetaskgraph_core::GraphDirection::Td),
            Self::Lr => Some(onetaskgraph_core::GraphDirection::Lr),
        }
    }
}

/// What `project graph` prints, stated whole: the contract every consumer of the verb builds
/// against, and its one statement. The README's "Drawing a project's dependency graph"
/// carries this text verbatim, and the journeys in `crates/onetaskgraph-e2e/tests/e2e/graph.rs`
/// hold the binary to it and the README to this text.
const GRAPH_CONTRACT: &str = "\
The graph:
  Every task of the project is drawn, across every page its source answers, with each
  dependency a project task has on another task. A task's rank is 0 when it depends on no
  task of the project, and otherwise one more than the highest rank among its prerequisites
  in the project; tasks outside the project have no rank. The number of ranks is one more
  than the highest rank, or 0 for a project with no tasks, and the widest rank is the most
  project tasks sharing one rank.

Direction:
  auto (the default) lays the graph out left to right (lr) when the widest rank holds more
  tasks than there are ranks, and top-down (td) otherwise; td and lr are taken as given.

Mermaid form (the default), UTF-8, every line ending in a newline:
  1. `flowchart TD` or `flowchart LR`, after auto is resolved.
  2. One line `  n<k>[\"<label>\"]` per task of the project, in topological order: each
     after every task of the project it depends on, ties broken by title and then by
     qualified id, each compared byte by byte. <k> counts from 1 in that order.
  3. One line `  x<k>[\"<label> (<qualified id>)\"]:::external` per task outside the
     project that a project task depends on, ordered by title and then qualified id, <k>
     counting from 1. The qualified id there is escaped as a label is.
  4. One line `  <prerequisite> --> <dependent>` per dependency, so an arrow points from the
     task depended on to the task that depends on it, ordered by the prerequisite's position
     and then the dependent's, every n node before every x node.
  5. Last, only when an x node was printed: `  classDef external stroke-dasharray: 5 5`.
  A project with no tasks prints the first line alone, which auto makes `flowchart TD`.

Grouped (--group-by <KEY>):
  A project task's group is the value its metadata holds under KEY when that is a non-empty
  JSON string. A task without the key, or holding null or \"\" under it, has no group; any
  other value is refused, naming the task's qualified id and the key, with nothing on
  standard output. A task outside the project never has a group. Groups are ordered by the
  position of their first member and numbered g<j> from 1 in that order. Grouping changes
  no rank, no direction, no node number and no edge order. The Mermaid lines are
  rearranged:
  1. The first line, as above.
  2. For each group in order: `  subgraph g<j>[\"<label of the group's value>\"]`; each
     member's node line indented by four spaces, in <k> order; each edge whose two ends are
     both members of this group, indented by four spaces, in edge order; then `  end`.
  3. The node line of each project task with no group, in <k> order.
  4. The x node lines.
  5. Every remaining edge, in edge order.
  6. The classDef line, as above.

Labels:
  A task's label is its title with each line break (\\r\\n, \\n or \\r) written as one space;
  then, in this order, # is written #35;, \" is written #quot;, < is written #lt; and > is
  written #gt;. Nothing else is altered. A group's label is its value escaped the same way,
  and the qualified id in an x line is escaped the same way too.

JSON form (--format json): one document and a newline, describing exactly the graph the
Mermaid form draws, and the form to read when a program has to know which task a node is:
  {
    \"schema_version\": 1,
    \"project\": \"<qualified project id>\",
    \"direction\": \"td\" | \"lr\",
    \"group_by\": \"<the --group-by key>\" | null,
    \"nodes\": [
      {\"key\": \"n1\", \"id\": \"<qualified task id>\", \"title\": \"<the title, unescaped>\",
       \"external\": false, \"group\": \"<the task's group>\" | null}
    ],
    \"edges\": [
      {\"from\": \"<qualified id of the prerequisite>\", \"to\": \"<qualified id of the dependent>\"}
    ]
  }
  direction is the resolved direction, never auto. nodes holds every n node and then every
  x node, in the Mermaid form's order; key is the Mermaid node id, external is true exactly
  for the x nodes, and group is null for a task with no group, for every external task, and
  for every task without --group-by. edges follows the Mermaid form's edge order.

Determinism:
  The output is a function of the project's task titles, their dependency edges, the
  qualified ids of the tasks outside it, the direction and, grouped, the key and each
  task's value under it. Two calls over an unchanged project print the same bytes.

Failure:
  An id naming no project, a source that cannot answer a read, a dependency naming a task
  its source does not hold, and tasks that depend on each other in a cycle each exit
  non-zero with nothing on standard output and the problem on standard error; a graph is
  never printed in part.
";

/// The arguments both copy verbs share.
///
/// A copy is one write into one destination, so there is no paging, no `--explain` and no
/// `--allow-partial` here: a partial write is not an answer a caller could act on.
#[derive(Debug, Args)]
pub struct CopyArgs {
    /// The configured source to copy into. A source name, never a qualified id.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — a `SourceName` here would move
    /// the refusal into clap, which reports it as an invalid *invocation* (exit 2) under
    /// clap's own wording, for the reason recorded on `SelectionArgs::source`. A name
    /// that cannot be a source name and one that names no configured source are the same
    /// typo, and both owe the same next action.
    #[arg(long, value_name = "SOURCE")]
    pub to: String,

    /// Re-establish a lost correspondence by matching on `title` or on a metadata key.
    #[arg(long = "match-by", value_name = "KEY")]
    pub match_by: Option<String>,

    /// Create a new destination item when a recorded origin names nothing there.
    #[arg(long)]
    pub recreate: bool,

    /// Perform every read, write nothing, and report what would have happened.
    ///
    /// A dry run keeps no delivered task in step, so its `delivered` list is always empty —
    /// which says nothing about whether any delivered task would have moved.
    #[arg(long = "dry-run")]
    pub dry_run: bool,

    #[command(flatten)]
    pub term_scope: TermScopeArgs,
}

/// `onetaskgraph task copy`.
#[derive(Debug, Args)]
pub struct TaskCopyArgs {
    /// The qualified ids to copy, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — a `GlobalId` here would refuse an
    /// unqualified id as a bad invocation, under clap's wording, for the reason recorded
    /// on `ShowArgs::id`. `qualified` in `main` converts through `GlobalId::from_str` and
    /// says what a qualified id is and where to read the configured names.
    #[arg(value_name = "ID", required = true)]
    pub id: Vec<String>,

    /// Create each task at the destination without looking for a counterpart first.
    ///
    /// You assert the destination holds none — typically because you have just asked it
    /// yourself — so the copy sends no origin lookup at all. That is sound because the lookup
    /// is GitHub's search index and board filter, which lag a fresh write by the same amount
    /// whoever asks: repeating your own query here could find nothing yours did not. Refused
    /// beside --match-by and --recreate, which are ways of looking, and for a task whose own
    /// link or origin already names an item at the destination.
    // llmlint: ignore-block[invalid_states_unrepresentable] As `CopyRequest::create`: one enum of the ways a copy finds its target would replace `--match-by` and `--recreate`, which `CopyArgs` shares with `project copy` and `document copy`, so `create` is one more flag beside them, and the one combination it makes possible that means nothing is refused by `Engine::copy` as `EngineError::CreateWith`, naming both flags, before anything is read.
    #[arg(long)]
    pub create: bool,
    // llmlint: ignore-end[invalid_states_unrepresentable]
    #[command(flatten)]
    pub copy: CopyArgs,
}

/// `onetaskgraph project copy`.
#[derive(Debug, Args)]
pub struct ProjectCopyArgs {
    /// The qualified id to copy, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `TaskCopyArgs::id`.
    #[arg(value_name = "ID")]
    pub id: String,

    /// Copy the project alone, leaving the tasks in it where they are.
    #[arg(long = "no-tasks")]
    pub no_tasks: bool,

    /// Copy the project and exactly this task of it, `<source>:<native-id>`; repeat it to
    /// name more. A task not named is not read at the destination, not written and not
    /// reported, and nothing is reported orphaned.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `TaskCopyArgs::id`.
    #[arg(long = "member", value_name = "TASK-ID", conflicts_with = "no_tasks")]
    pub member: Vec<String>,

    #[command(flatten)]
    pub copy: CopyArgs,
}

/// `onetaskgraph document copy`.
#[derive(Debug, Args)]
pub struct DocumentCopyArgs {
    /// The qualified ids to copy, `<source>:<native-id>`.
    ///
    /// llmlint: ignore[invalid_states_unrepresentable] — as `TaskCopyArgs::id`.
    #[arg(value_name = "ID", required = true)]
    pub id: Vec<String>,

    #[command(flatten)]
    pub copy: CopyArgs,
}

/// `onetaskgraph search`.
#[derive(Debug, Args)]
pub struct SearchArgs {
    /// What to look for.
    #[arg(value_name = "TEXT")]
    pub text: String,

    /// Which fields to look in.
    #[arg(long = "in", value_name = "FIELDS", default_value = "both")]
    pub fields: FieldsArg,

    /// Which entities to search.
    #[arg(long, value_name = "KIND", default_value = "both")]
    pub kind: KindArg,

    #[command(flatten)]
    pub selection: SelectionArgs,

    #[command(flatten)]
    pub paging: PageArgs,
}

/// A status category, as the command line spells it.
///
/// A command-line mirror of [`StatusCategory`] rather than that type itself, for the
/// reason [`Format`] carries: deriving clap's `ValueEnum` on a contract type would put
/// clap into the plugin contract's dependencies for the sake of one flag.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum StatusArg {
    /// Written down but not yet committed to as work.
    Draft,
    /// Known about, not yet accepted as ready to work.
    Backlog,
    /// Accepted and ready to be picked up, and nothing has claimed it.
    Todo,
    /// Claimed by work that will do it, and not yet started.
    Queued,
    /// Being worked on.
    InProgress,
    /// Finished.
    Done,
    /// Abandoned.
    Cancelled,
    /// The source reported a status this vocabulary cannot place.
    Unknown,
}

impl StatusArg {
    /// The contract's own category.
    #[must_use]
    pub fn category(self) -> StatusCategory {
        match self {
            Self::Draft => StatusCategory::Draft,
            Self::Backlog => StatusCategory::Backlog,
            Self::Todo => StatusCategory::Todo,
            Self::Queued => StatusCategory::Queued,
            Self::InProgress => StatusCategory::InProgress,
            Self::Done => StatusCategory::Done,
            Self::Cancelled => StatusCategory::Cancelled,
            Self::Unknown => StatusCategory::Unknown,
        }
    }
}

/// A priority, as the command line spells it.
///
/// A command-line mirror of [`Priority`] rather than that type itself, for the reason
/// [`StatusArg`] is one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum PriorityArg {
    /// No priority is set.
    None,
    /// Drop everything for it.
    Urgent,
    /// Next, before the rest.
    High,
    /// In its turn.
    Medium,
    /// When there is nothing more pressing.
    Low,
}

impl PriorityArg {
    /// The contract's own priority.
    #[must_use]
    pub fn priority(self) -> Priority {
        match self {
            Self::None => Priority::None,
            Self::Urgent => Priority::Urgent,
            Self::High => Priority::High,
            Self::Medium => Priority::Medium,
            Self::Low => Priority::Low,
        }
    }
}

/// A classification, as the command line spells it.
///
/// A command-line mirror of [`Classification`] rather than that type itself, for the reason
/// [`StatusArg`] is one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum ClassificationArg {
    /// Anybody who may read the destination may read it.
    Public,
    /// Written only to a source declared private whose backend agrees.
    Private,
}

impl ClassificationArg {
    /// The contract's own classification.
    #[must_use]
    pub fn classification(self) -> Classification {
        match self {
            Self::Public => Classification::Public,
            Self::Private => Classification::Private,
        }
    }
}

/// Which private repositories a writing verb's public-boundary check derives its terms from.
// llmlint: ignore-block[invalid_states_unrepresentable] clap's derive has no one-field spelling for "a list, or explicitly none": `conflicts_with` refuses both flags at once where they are typed (exit 2), and `scope` maps them to the one `Option<Vec<String>>` the engine takes before anything reads them.
#[derive(Debug, Default, Args)]
pub struct TermScopeArgs {
    /// Derive the public-boundary check's private terms only from this repository
    /// (`host/owner/name`). Repeat for several; left out, the check derives them from every
    /// private repository its policy knows of.
    #[arg(long = "term-scope", value_name = "REPOSITORY")]
    pub term_scope: Vec<String>,

    /// Derive no private terms at all.
    #[arg(long = "term-scope-empty", conflicts_with = "term_scope")]
    pub term_scope_empty: bool,
}
// llmlint: ignore-end[invalid_states_unrepresentable]

impl TermScopeArgs {
    /// The scope the engine takes: `None` when neither flag is given, an empty list for
    /// `--term-scope-empty`, and the repositories named otherwise.
    #[must_use]
    pub fn scope(&self) -> Option<Vec<String>> {
        if self.term_scope_empty {
            Some(Vec::new())
        } else if self.term_scope.is_empty() {
            None
        } else {
            Some(self.term_scope.clone())
        }
    }
}

/// Which fields a search covers, as the command line spells it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum FieldsArg {
    /// Titles only.
    Title,
    /// Bodies only.
    Content,
    /// Either one matching is a match.
    Both,
}

impl FieldsArg {
    /// The contract's own field selector.
    #[must_use]
    pub fn fields(self) -> TextFields {
        match self {
            Self::Title => TextFields::Title,
            Self::Content => TextFields::Content,
            Self::Both => TextFields::TitleOrContent,
        }
    }
}

/// Which way a dependency walk goes, as the command line spells it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum DirectionArg {
    /// What this item depends on.
    DependsOn,
    /// What depends on this item.
    DependedOnBy,
}

impl DirectionArg {
    /// The contract's own direction.
    #[must_use]
    pub fn direction(self) -> Direction {
        match self {
            Self::DependsOn => Direction::DependsOn,
            Self::DependedOnBy => Direction::DependedOnBy,
        }
    }
}

/// Which entities a search covers, as the command line spells it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum KindArg {
    /// Tasks only.
    Task,
    /// Projects only.
    Project,
    /// Both, interleaved.
    Both,
}

impl KindArg {
    /// The engine's own search scope.
    #[must_use]
    pub fn kind(self) -> SearchKind {
        match self {
            Self::Task => SearchKind::Tasks,
            Self::Project => SearchKind::Projects,
            Self::Both => SearchKind::Both,
        }
    }
}

/// What `onetaskgraph config` can do.
#[derive(Debug, Subcommand)]
pub enum ConfigCommand {
    /// Show every setting, with the layer its value came from.
    ///
    /// The layer is named exactly: which document, which environment variable, or
    /// which flag. Rendered as JSON when `output` is `json` — which `--json` sets.
    Show,
}

/// The command-line layer: any setting, at the top of the stack.
#[derive(Debug, Args)]
pub struct Overrides {
    /// Set any setting: --set sources.work.config.root=/tmp/tasks
    ///
    /// The path is the same dotted path a document uses and the same one the
    /// `ONETASKGRAPH_` variables encode, so one name works at all three layers.
    #[arg(long = "set", value_name = "PATH=VALUE", global = true)]
    pub set: Vec<String>,

    /// How many items one page holds.
    ///
    /// Refused at zero here rather than at load: this flag parses on every verb, so a
    /// value only the configuration loader would have caught is one the verbs that do
    /// not load a configuration would accept in silence.
    #[arg(
        long,
        value_name = "N",
        global = true,
        value_parser = clap::value_parser!(u32).range(1..)
    )]
    pub page_size: Option<u32>,

    /// Which sources answer when a command names none.
    #[arg(long, value_name = "NAMES", value_delimiter = ',', global = true)]
    pub default_sources: Option<Vec<String>>,

    /// How output is rendered.
    #[arg(long, value_name = "FORMAT", global = true, conflicts_with = "json")]
    pub output: Option<Format>,

    /// Shorthand for --output json.
    #[arg(long, global = true)]
    pub json: bool,

    // llmlint: ignore-block[invalid_states_unrepresentable] Two presence-only flags, as `json` beside `output` above: clap's derive has no one-field spelling for a pair of opposing switches. Both fields are private, so only clap builds them, `conflicts_with` refuses both at once where they are typed (exit 2), and `layer` maps each to the one `interactive` setting immediately.
    /// Prompt for what a command was not given (the `interactive` setting's default).
    #[arg(long, global = true, conflicts_with = "no_interactive")]
    interactive: bool,

    /// Never prompt: refuse what a command was not given instead. For scripts and automation.
    #[arg(long = "no-interactive", global = true)]
    no_interactive: bool,
    // llmlint: ignore-end[invalid_states_unrepresentable]
}

impl Overrides {
    /// These flags as one configuration layer.
    ///
    /// # Errors
    ///
    /// Returns a message naming the flag when a `--set` argument is not
    /// `PATH=VALUE`, or its path addresses nothing.
    pub fn layer(&self) -> Result<Layer, String> {
        let mut settings = Vec::new();

        if let Some(page_size) = self.page_size {
            settings.push(at("page_size", Value::from(page_size), "--page-size"));
        }
        if let Some(names) = &self.default_sources {
            let names: Vec<Value> = names.iter().map(|name| Value::from(name.clone())).collect();
            settings.push(at(
                "default_sources",
                Value::Array(names),
                "--default-sources",
            ));
        }
        if let Some(format) = self.output {
            settings.push(at("output", format.setting(), "--output"));
        }
        if self.json {
            settings.push(at("output", Value::from("json"), "--json"));
        }
        if self.interactive {
            settings.push(at("interactive", Value::Bool(true), "--interactive"));
        }
        if self.no_interactive {
            settings.push(at("interactive", Value::Bool(false), "--no-interactive"));
        }

        // Last, so `--set output=text` beats `--json`: the general form is the more
        // specific instruction, and a caller who spells a path out means it.
        for assignment in &self.set {
            settings.push(assignment_setting(assignment)?);
        }

        Ok(Layer::new(settings))
    }
}

/// How output is rendered, as the command line accepts it.
///
/// A command-line mirror of [`OutputFormat`] rather than that type itself, because
/// deriving clap's `ValueEnum` on it would put clap into the engine's dependencies for
/// the sake of one flag. The two cannot disagree about *spelling*: [`Format::setting`]
/// produces its value by serialising the `OutputFormat` it stands for, so what reaches
/// the configuration is whatever the engine's own type writes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum Format {
    /// For a person reading a terminal.
    Text,
    /// For a program.
    Json,
}

impl Format {
    /// This format as the `output` setting's value.
    #[must_use]
    pub fn setting(self) -> Value {
        let format = match self {
            Self::Text => OutputFormat::Text,
            Self::Json => OutputFormat::Json,
        };
        serde_json::to_value(format).expect("an output format renders as JSON")
    }
}

/// One setting at a path this binary spells itself.
fn at(key: &str, value: Value, flag: &str) -> Setting {
    Setting {
        key: SettingPath::parse(key).expect("a path this binary spells has no empty segment"),
        value,
        origin: Origin::Flag {
            flag: flag.to_owned(),
        },
    }
}

/// One `--set PATH=VALUE` argument.
fn assignment_setting(assignment: &str) -> Result<Setting, String> {
    let Some((path, value)) = assignment.split_once('=') else {
        return Err(format!(
            "--set {assignment}: that is not an assignment\n\
             next: write it as --set PATH=VALUE, for example --set page_size=10."
        ));
    };
    Ok(Setting {
        key: SettingPath::parse(path).map_err(|error| format!("--set {error}"))?,
        value: value_from_text(value),
        origin: Origin::Flag {
            flag: format!("--set {path}"),
        },
    })
}