workspace-mgr 0.8.8

use std::path::PathBuf;

use clap::{Args, Parser, Subcommand};

use crate::config::StorageTarget;
use crate::manifest::TaskKind;
use crate::output::Format;

#[derive(Debug, Parser)]
#[command(
    name = "workspace-mgr",
    version,
    about = "Fixed-policy repository workspace manager for coding agents",
    subcommand_required = true,
    arg_required_else_help = true
)]
pub struct Cli {
    #[arg(
        long,
        global = true,
        value_enum,
        default_value = "human",
        env = "WORKSPACE_MGR_FORMAT"
    )]
    pub format: Format,

    #[command(subcommand)]
    pub command: Command,
}

#[derive(Debug, Subcommand)]
pub enum Command {
    /// Verify the native storage engine and Git installation.
    #[command(long_about = crate::command_guidance::command("setup"))]
    Setup(SetupArgs),

    /// Adopt or reconcile a repository, including legacy storage migration.
    #[command(alias = "init", long_about = crate::command_guidance::command("manage"))]
    Manage(ManageArgs),

    /// Print the shared workspace model and effective repository instructions.
    #[command(long_about = crate::command_guidance::command("instructions"))]
    Instructions(InstructionsArgs),

    /// Diagnose one task or all tasks, including local/S3 storage integrity.
    #[command(long_about = crate::command_guidance::command("doctor"))]
    Doctor(DoctorArgs),

    /// Inspect repository configuration.
    #[command(long_about = crate::command_guidance::command("config"))]
    Config(ConfigArgs),

    /// Manage task scaffolding and lifecycle.
    #[command(long_about = crate::command_guidance::command("task"))]
    Task(TaskArgs),

    /// Preview a scoped repository transaction without publishing.
    #[command(long_about = crate::command_guidance::command("plan"))]
    Plan(PlanArgs),

    /// Publish a scoped repository transaction.
    #[command(long_about = crate::command_guidance::command("publish"))]
    Publish(PublishCommandArgs),

    /// Inspect or change whether content is stored in Git or S3.
    #[command(long_about = crate::command_guidance::command("storage"))]
    Storage(StorageArgs),

    /// Move a path while preserving its storage placement.
    #[command(long_about = crate::command_guidance::command("move"))]
    Move(MoveArgs),

    /// Organize done tasks, preserving tasks with open pull requests.
    #[command(long_about = crate::command_guidance::command("archive"))]
    Archive(ArchiveArgs),

    /// Delete a path and permanently purge obsolete S3 versions after publication.
    #[command(long_about = crate::command_guidance::command("remove"))]
    Remove(RemoveArgs),

    /// Keep content locally, ignore it, and remove it from Git/S3 after publication.
    #[command(long_about = crate::command_guidance::command("untrack"))]
    Untrack(UntrackArgs),

    /// Safely update a shared checkout and hydrate incoming stored data.
    #[command(long_about = crate::command_guidance::command("refresh"))]
    Refresh(RefreshArgs),
}

#[derive(Debug, Args)]
pub struct SetupArgs {
    /// Legacy compatibility option; native storage needs no runtime directory.
    #[arg(long)]
    pub runtime_dir: Option<PathBuf>,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct RepoArgs {
    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Args)]
pub struct DoctorArgs {
    /// Exact task ID, current name, slug, or path; omit to inspect all tasks.
    pub task: Option<String>,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Args)]
pub struct ManageArgs {
    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    /// Configure an S3 bucket at this non-secret URL.
    #[arg(long)]
    pub s3_url: Option<String>,

    /// Optional S3-compatible API endpoint for managed storage.
    #[arg(long, requires = "s3_url")]
    pub s3_endpoint_url: Option<String>,

    #[arg(long)]
    pub dry_run: bool,

    /// Cancel an unfinished storage import while retaining all remote data.
    #[arg(long, conflicts_with_all = ["s3_url", "s3_endpoint_url"])]
    pub cancel_migration: bool,
}

#[derive(Debug, Args)]
pub struct InstructionsArgs {
    /// Optional topic: model, core, task, publish, artifacts, storage, shared-checkout, infrastructure, or repository.
    pub topic: Option<String>,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Args)]
pub struct ConfigArgs {
    #[command(subcommand)]
    pub command: ConfigCommand,
}

#[derive(Debug, Subcommand)]
pub enum ConfigCommand {
    /// Print and validate the effective repository configuration.
    #[command(long_about = crate::command_guidance::command("config show"))]
    Show(RepoArgs),
}

#[derive(Debug, Args)]
pub struct TaskArgs {
    #[command(subcommand)]
    pub command: TaskCommand,
}

#[derive(Debug, Subcommand)]
pub enum TaskCommand {
    /// List current tasks, including grouped directories and legacy candidates.
    #[command(long_about = crate::command_guidance::command("task list"))]
    List(TaskListArgs),
    /// Resolve an exact task ID, current name, slug, or path to its directory.
    #[command(long_about = crate::command_guidance::command("task path"))]
    Path(TaskPathArgs),
    /// Show a task's current metadata, manifest, and declared scopes.
    #[command(long_about = crate::command_guidance::command("task show"))]
    Show(TaskShowArgs),
    /// Create a deliverable directory or a private infrastructure manifest on the shared branch.
    #[command(long_about = crate::command_guidance::command("task create"))]
    Create(TaskCreateArgs),
    /// Attach current task metadata to a legacy directory, optionally preserving a reviewed PR hint.
    #[command(long_about = crate::command_guidance::command("task adopt"))]
    Adopt(TaskAdoptArgs),
    /// Change a task's current slug while preserving its identity and review branch.
    #[command(long_about = crate::command_guidance::command("task rename"))]
    Rename(TaskRenameArgs),
    /// Upgrade current task configuration without inspecting historical payloads.
    #[command(long_about = crate::command_guidance::command("task upgrade"))]
    Upgrade(TaskUpgradeArgs),
    /// Inspect the resolved task scope and working changes.
    #[command(long_about = crate::command_guidance::command("task status"))]
    Status(TaskStatusArgs),
    /// Permanently discard an unmerged task after its pull request is closed.
    #[command(long_about = crate::command_guidance::command("task discard"))]
    Discard(TaskDiscardArgs),
    /// Record the user's explicit approval of a cloud-usage limit for this task.
    #[command(long_about = crate::command_guidance::command("task approve-cloud-usage"))]
    ApproveCloudUsage(TaskApproveCloudUsageArgs),
}

#[derive(Debug, Args)]
pub struct TaskListArgs {
    /// Case-insensitive substring in a task's ID, name, slug, title, or path.
    pub query: Option<String>,

    #[arg(long, value_enum)]
    pub kind: Option<TaskKind>,

    /// Filter by current directory placement; this does not imply completion.
    #[arg(long, value_enum)]
    pub placement: Option<crate::task_catalog::Placement>,

    /// Print repository-relative deliverable paths, omitting infrastructure tasks.
    #[arg(long)]
    pub paths: bool,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Args)]
pub struct TaskPathArgs {
    pub selector: String,

    /// Return a repository-root-relative path instead of an absolute path.
    #[arg(long)]
    pub relative: bool,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Args)]
pub struct TaskShowArgs {
    pub selector: String,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Args)]
pub struct TaskUpgradeArgs {
    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    #[arg(long)]
    pub manifest: Option<PathBuf>,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct TaskRenameArgs {
    pub new_slug: String,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    #[arg(long)]
    pub manifest: Option<PathBuf>,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct ArchiveArgs {
    /// Tasks to organize; omitted to inspect top-level deliverable tasks.
    pub paths: Vec<String>,

    /// Date grouping using the task's creation year and month.
    #[arg(long, default_value = "{year}/{month}")]
    pub layout: String,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    #[arg(long)]
    pub manifest: Option<PathBuf>,

    /// Inspect tasks with no open pull requests without moving content.
    #[arg(long)]
    pub dry_run: bool,

    /// Restore an unpublished archive attempt, preserving every local payload.
    #[arg(long, conflicts_with = "layout")]
    pub cancel: bool,
}

#[derive(Debug, Args)]
pub struct TaskAdoptArgs {
    pub path: String,
    #[arg(long)]
    pub pull_request: Option<u64>,
    #[arg(long)]
    pub title: String,
    #[arg(long)]
    pub purpose: String,
    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
    #[arg(long)]
    pub manifest: Option<PathBuf>,
    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct TaskCreateArgs {
    pub slug: String,

    #[arg(long)]
    pub title: String,

    #[arg(long)]
    pub purpose: String,

    #[arg(long, value_enum, default_value = "deliverable")]
    pub kind: TaskKind,

    /// Declare an infrastructure path. Repeat for multiple paths.
    #[arg(long = "scope")]
    pub scopes: Vec<String>,

    /// Explain why the declared infrastructure paths are authorized.
    #[arg(long, requires = "scopes")]
    pub scope_note: Option<String>,

    #[arg(long, hide = true)]
    pub timestamp: Option<String>,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct TaskStatusArgs {
    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    #[arg(long)]
    pub manifest: Option<PathBuf>,
}

#[derive(Debug, Args)]
pub struct TaskDiscardArgs {
    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    #[arg(long)]
    pub manifest: Option<PathBuf>,

    /// Inspect the exact destructive scope and save a private confirmation plan.
    #[arg(long, conflicts_with = "confirm")]
    pub dry_run: bool,

    /// Confirm the exact task ID after the agent closes or verifies absence of its PR.
    #[arg(long, value_name = "TASK_ID", conflicts_with = "dry_run")]
    pub confirm: Option<String>,
}

#[derive(Debug, Args)]
pub struct TaskApproveCloudUsageArgs {
    /// Approved limit: a byte count or a size such as 1.5GiB or 2GB.
    #[arg(long, value_parser = crate::cloud_usage::parse_size)]
    pub limit: u64,

    /// The user's decision from this chat, on one line.
    #[arg(long)]
    pub note: String,

    #[arg(long)]
    pub scope_note: Option<String>,

    #[arg(long)]
    pub allow_non_shared_head: bool,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    #[arg(long)]
    pub manifest: Option<PathBuf>,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Clone, Args)]
pub struct PlanArgs {
    #[arg(long)]
    pub manifest: Option<PathBuf>,

    #[arg(long = "include")]
    pub include: Vec<String>,

    #[arg(long)]
    pub scope_note: Option<String>,

    #[arg(long)]
    pub allow_non_shared_head: bool,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Clone, Args)]
pub struct PublishCommandArgs {
    #[arg(long)]
    pub manifest: Option<PathBuf>,

    #[arg(short = 'm', long)]
    pub message: String,

    #[arg(long = "include")]
    pub include: Vec<String>,

    #[arg(long)]
    pub scope_note: Option<String>,

    #[arg(long)]
    pub allow_non_shared_head: bool,

    #[arg(long)]
    pub dry_run: bool,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Args)]
pub struct StorageArgs {
    #[command(subcommand)]
    pub command: StorageCommand,
}

#[derive(Debug, Subcommand)]
pub enum StorageCommand {
    /// Show the effective Git/S3 placement of paths in the task scope.
    #[command(long_about = crate::command_guidance::command("storage status"))]
    Status(StorageStatusArgs),
    /// Explicitly place paths in Git or S3. This changes local desired state only.
    #[command(long_about = crate::command_guidance::command("storage set"))]
    Set(StorageSetArgs),
    /// Remove an explicit choice and reapply the repository's automatic policy.
    #[command(long_about = crate::command_guidance::command("storage reset"))]
    Reset(StorageResetArgs),
    /// Materialize S3 content without publishing anything.
    #[command(long_about = crate::command_guidance::command("storage hydrate"))]
    Hydrate(StorageHydrateArgs),
}

#[derive(Debug, Clone, Args)]
pub struct ScopedArgs {
    #[arg(long)]
    pub manifest: Option<PathBuf>,

    #[arg(long = "include")]
    pub include: Vec<String>,

    #[arg(long)]
    pub scope_note: Option<String>,

    #[arg(long, default_value = ".")]
    pub repo: PathBuf,
}

#[derive(Debug, Args)]
pub struct StorageStatusArgs {
    #[command(flatten)]
    pub scoped: ScopedArgs,

    pub paths: Vec<String>,
}

#[derive(Debug, Args)]
pub struct StorageSetArgs {
    #[command(flatten)]
    pub scoped: ScopedArgs,

    #[arg(required = true)]
    pub paths: Vec<String>,

    #[arg(long, value_enum)]
    pub to: StorageTarget,

    #[arg(long)]
    pub reason: String,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct StorageResetArgs {
    #[command(flatten)]
    pub scoped: ScopedArgs,

    #[arg(required = true)]
    pub paths: Vec<String>,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct StorageHydrateArgs {
    #[command(flatten)]
    pub scoped: ScopedArgs,

    pub paths: Vec<String>,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct MoveArgs {
    #[command(flatten)]
    pub scoped: ScopedArgs,

    pub old_path: String,
    pub new_path: String,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct RemoveArgs {
    #[command(flatten)]
    pub scoped: ScopedArgs,

    #[arg(required = true)]
    pub paths: Vec<String>,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct UntrackArgs {
    #[command(flatten)]
    pub scoped: ScopedArgs,

    #[arg(required = true)]
    pub paths: Vec<String>,

    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
pub struct RefreshArgs {
    #[arg(long, default_value = ".")]
    pub repo: PathBuf,

    #[arg(long)]
    pub dry_run: bool,
}

#[cfg(test)]
mod tests {
    use clap::Parser;

    use super::{Cli, Command, TaskArgs, TaskCommand};

    #[test]
    fn documented_command_shapes_are_accepted_by_clap() {
        let examples: &[&[&str]] = &[
            &["setup", "--dry-run"],
            &[
                "setup",
                "--runtime-dir",
                "/tmp/workspace-mgr-runtime",
                "--dry-run",
            ],
            &["manage"],
            &[
                "manage",
                "--s3-url",
                "s3://example-bucket/workspace",
                "--s3-endpoint-url",
                "https://s3.example.invalid",
                "--dry-run",
            ],
            &["instructions"],
            &["instructions", "model"],
            &["instructions", "storage", "--repo", "/tmp/repository"],
            &["--format", "json", "instructions", "publish"],
            &["doctor", "--repo", "/tmp/repository"],
            &["doctor", "example-task", "--repo", "/tmp/repository"],
            &["config", "show", "--repo", "/tmp/repository"],
            &[
                "task",
                "upgrade",
                "--manifest",
                "/tmp/task/.workspace-mgr-task.toml",
                "--dry-run",
            ],
            &[
                "task",
                "create",
                "training-report",
                "--title",
                "Training report",
                "--purpose",
                "Produce the final training report",
                "--dry-run",
            ],
            &[
                "task",
                "create",
                "shared-policy",
                "--kind",
                "infrastructure",
                "--title",
                "Shared policy",
                "--purpose",
                "Update repository policy",
                "--scope",
                "AGENTS.md",
                "--scope",
                ".github/workflows/ci.yml",
                "--scope-note",
                "The user requested this infrastructure change",
            ],
            &["task", "status", "--manifest", "task/manifest.toml"],
            &[
                "task",
                "rename",
                "current-topic",
                "--manifest",
                "task/manifest.toml",
                "--dry-run",
            ],
            &[
                "task",
                "approve-cloud-usage",
                "--limit",
                "1.5GB",
                "--note",
                "The user approved 1.5 GB for the training checkpoints",
            ],
            &[
                "task",
                "approve-cloud-usage",
                "--limit",
                "3GiB",
                "--note",
                "The user approved 3 GiB in this chat",
                "--manifest",
                "task/manifest.toml",
                "--dry-run",
            ],
            &[
                "task",
                "approve-cloud-usage",
                "--limit",
                "2000000000",
                "--note",
                "The user approved 2000000000 bytes",
                "--repo",
                "/tmp/repository",
            ],
            &[
                "task",
                "approve-cloud-usage",
                "--limit",
                "2GiB",
                "--note",
                "The user approved 2 GiB in this chat",
                "--allow-non-shared-head",
                "--scope-note",
                "The user selected an alternate checkout",
            ],
            &["storage", "status"],
            &[
                "storage",
                "status",
                "task/results/model.bin",
                "--manifest",
                "task/manifest.toml",
            ],
            &[
                "storage",
                "set",
                "task/report.pdf",
                "task/summary.txt",
                "--to",
                "git",
                "--reason",
                "Review these files directly",
            ],
            &[
                "storage",
                "set",
                "task/data",
                "--to",
                "s3",
                "--reason",
                "Retain the dataset",
                "--dry-run",
            ],
            &["storage", "reset", "task/data"],
            &["storage", "hydrate", "task/data/example.csv"],
            &["move", "task/old.bin", "task/new.bin", "--dry-run"],
            &["remove", "task/obsolete.bin", "--dry-run"],
            &["untrack", "task/local.bin", "--dry-run"],
            &[
                "plan",
                "--include",
                "docs/shared.md",
                "--scope-note",
                "The user requested this shared documentation update",
            ],
            &[
                "plan",
                "--allow-non-shared-head",
                "--scope-note",
                "The user selected an alternate checkout",
            ],
            &["publish", "-m", "Publish the training report"],
            &[
                "publish",
                "--message",
                "Publish shared documentation",
                "--include",
                "docs/shared.md",
                "--scope-note",
                "The user requested this shared documentation update",
                "--dry-run",
            ],
            &["refresh", "--dry-run"],
        ];

        for args in examples {
            let argv = std::iter::once("workspace-mgr").chain(args.iter().copied());
            Cli::try_parse_from(argv).unwrap_or_else(|error| {
                panic!("documented command failed to parse: {args:?}\n{error}")
            });
        }
    }

    #[test]
    fn approval_limits_are_parsed_as_exact_byte_counts() {
        let limit = |raw: &str| -> Result<u64, clap::Error> {
            let cli = Cli::try_parse_from([
                "workspace-mgr",
                "task",
                "approve-cloud-usage",
                "--limit",
                raw,
                "--note",
                "Approved in chat",
            ])?;
            match cli.command {
                Command::Task(TaskArgs {
                    command: TaskCommand::ApproveCloudUsage(args),
                }) => Ok(args.limit),
                other => panic!("unexpected command {other:?}"),
            }
        };
        assert_eq!(limit("1.5GB").unwrap(), 1_500_000_000);
        assert_eq!(limit("1.5 GB").unwrap(), 1_500_000_000);
        assert_eq!(limit("3GiB").unwrap(), 3 << 30);
        assert_eq!(limit("2000000000").unwrap(), 2_000_000_000);
        for invalid in ["1G", "1.5", "-1GB", "20000000 TB"] {
            assert!(limit(invalid).is_err(), "{invalid:?} was accepted");
        }
        assert!(
            Cli::try_parse_from([
                "workspace-mgr",
                "task",
                "approve-cloud-usage",
                "--limit",
                "2GB"
            ])
            .is_err(),
            "the user's decision must be recorded"
        );
    }

    #[test]
    fn read_only_commands_do_not_expose_meaningless_mutation_flags() {
        assert!(Cli::try_parse_from(["workspace-mgr", "plan", "--dry-run"]).is_err());
        assert!(Cli::try_parse_from(["workspace-mgr", "plan", "-m", "unused"]).is_err());
        assert!(Cli::try_parse_from(["workspace-mgr", "storage", "status", "--dry-run"]).is_err());
    }
}