/** Native file commands implemented by cli/dench.ts. API operations are not
 * necessarily CLI commands: files.mkdir is available only through the API/SDK. */
type FileCommandArguments = {
  command: string;
  positionals: readonly [number, number];
  values: string[];
  switches: string[];
  flagPositionals: Record<string, readonly [number, number | null]>;
  usage: string;
  description: string;
  examples: string[];
  notes: string[];
};

export const FILE_COMMAND_ARGUMENTS: FileCommandArguments[] = [
  {
    command: "files ls",
    positionals: [0, 1] as const,
    values: [],
    switches: ["--recursive", "-r"],
    flagPositionals: {},
    usage: "dench files ls [<path>] [--recursive|-r] [--json]",
    description: "List workspace files; the default path is /.",
    examples: ["dench files ls /reports --recursive --json"],
    notes: ["--recursive (or -r) includes descendants."],
  },
  {
    command: "files cat",
    positionals: [1, 1] as const,
    values: [],
    switches: [],
    flagPositionals: {},
    usage: "dench files cat <path> [--json]",
    description: "Read a workspace file's inline text.",
    examples: ["dench files cat /reports/summary.md"],
    notes: [
      "Use cat for virtual files such as IDENTITY.md and ORGANISATION.md, which have no download blob.",
      "For binary files or files without inline text, use files download.",
    ],
  },
  {
    command: "files write",
    positionals: [1, 1] as const,
    values: [],
    switches: [],
    flagPositionals: {},
    usage: "dench files write <path> [--json]",
    description: "Write a workspace file's text from stdin.",
    examples: [
      "dench files write /reports/summary.md --json < ./summary.md",
      "printf '%s\\n' 'Report ready.' | dench files write /reports/summary.md --json",
    ],
    notes: [
      "The destination path is required. Pipe or redirect the raw UTF-8 file text into stdin.",
      "--json controls the result format; stdin is file content, not an API JSON envelope. No --stdin, --content or --file flag is supported.",
      "Writing replaces the complete text; empty stdin writes an empty file.",
    ],
  },
  {
    command: "files mv",
    positionals: [2, 2] as const,
    values: [],
    switches: [],
    flagPositionals: {},
    usage: "dench files mv <src> <dst> [--json]",
    description: "Move or rename a workspace file or directory.",
    examples: ["dench files mv /reports/draft.md /reports/summary.md --json"],
    notes: ["Both paths refer to workspace storage, not local disk."],
  },
  {
    command: "files rm",
    positionals: [1, 1] as const,
    values: [],
    switches: ["--recursive", "-r"],
    flagPositionals: {},
    usage: "dench files rm <path> [--recursive|-r] [--json]",
    description: "Remove a workspace file or directory.",
    examples: ["dench files rm /reports/old --recursive --json"],
    notes: [
      "Directories require --recursive (or -r). An absent path is already removed.",
    ],
  },
  {
    command: "files download",
    positionals: [1, 2] as const,
    values: [],
    switches: ["--url"],
    flagPositionals: {},
    usage: "dench files download <path> [<local-dest>] [--url] [--json]",
    description:
      "Download workspace bytes to local disk, or print a signed URL.",
    examples: [
      "dench files download /reports/summary.pdf ./summary.pdf --json",
      "dench files download /reports/summary.pdf --url --json",
    ],
    notes: [
      "Without --url, downloads directories recursively and defaults the local destination to the path's basename (/ becomes workspace).",
      "--url prints a short-lived signed URL for one stored file instead of saving locally; local-dest is unused in this mode.",
    ],
  },
];

export const FILE_COMMAND_NOTES = [
  "Workspace paths are POSIX paths under /workspace; /reports/a.md and /workspace/reports/a.md address the same file.",
  "These commands read or update workspace storage. Use dench stage to upload local files or directories.",
];