[FEATURE] Enable fine-grain control over CLI output, for improved usability in scripting.

[jakcron]

About

To improve usability in scripting use-cases, three modes shall be provided to control what output is written to stdout/stderr.

Design

Modes

• Silent Mode - Omit presenting file information to output
  • Enabled with CLI option -q/--quiet
• Verbose Mode - Where information has been summarised, present the full version instead
  • Enabled with CLI option -v/--verbose
• Verify Mode - Verify the file structures where possible, and present errors to output
  • Enabled with CLI option -y/--verify

Output Types

NSTool shall classify CLI output as one of three types:

• File Information (file structures, and filesystem trees, enum decoding, etc...)
  • These are printed to stdout.
  • These are the only output silenced in silent mode.
  • Where file information is too long (would exceed terminal history buffer) or redundant (unused fields) that information should be summarised
    • The unsummarised version should only be shown in verbose mode.
• Warnings & Progress Indicators (these inform the user of potential errors, and state of an operation)
  • These are printed to stderr.
  • This information is only shown in verbose mode.
  • These are prefixed in output with a tag [nstool::ClassNameHere LOG] ....
  • Progress indicators include output like Extracting X to Y....
• Errors (these inform the user of un-recoverable errors)
  • These are printed to stderr.
  • These will always be shown.
  • These are prefixed in output with a tag [nstool::ClassNameHere ERROR] ....
  • Note verification errors are only shown in verify mode.
  • Errors that have a hierarchy (like blocks, within an IVFC layer, within a IVFC image) should be summarised.
    • Granularity on specific element in the hierarchy should only be shown in verbose mode.

Requirements

• Maintain CLI argument backwards compatibility (Minor change)

[Clearmist]

I love this feature suggestion 😁 because you are thinking about how to make the output of the tool more easily read by other software. I have one suggestion about how to make the output super machine readable.

Output a valid JSON string containing the values you'd normally print when the --output-format "json" parameter is provided. Here are some examples:

Default tool behavior on an archive

From

[PartitionFs]
  Type:      Nested HFS0
  DirNum:    3
  FileNum:   8

To

{
    "partitionFileSystem": {
        "type": "Nested HFS0",
        "totals": {
            "directories": "3",
            "files": "8"
        }
    }
}

Listing file system

From

[GameCard/Header]
  CardHeaderVersion:      0
  RomSize:                1GB
  PackageId:              0x66a9c5a9c0f45087
  Flags:                  0x00
  SelSec:                 0x1
  SelT1Key:               0x2
  SelKey:                 0x0
[PartitionFs]
  Type:      Nested HFS0
  DirNum:    3
  FileNum:   8
[PartitionFs/Tree]
 gamecard:/
  update/
  normal/
  secure/
   d410961e1dc9a4fde688ff19f80a4a3f.nca
   1d57e359fdd5773e4a7030d4700ceece.nca
   e1db2c894276b8918377f0b4a26d8070.nca
   b34f8b09c419320be1f2966c2c3a609a.cnmt.nca
   04b55d1660cf95359b636ba1170a668f.nca
   db9912b1a244cd0eed73755c3cf42ca7.nca
   4ce4826de607d37626642db89151ac30.nca
   8ad12697d849c2cd3a7b12cf45682b8e.cnmt.nca

To

You will notice that each file on the system is its own object in the array instead of a single string element in the array. This makes extending the amount of information easier in the future. For example: if you eventually add the file size or header information for each file.

{
    "header": {
        "CardHeaderVersion": 0,
        "RomSize": "1GB",
        "PackageId": "0x66a9c5a9c0f45087",
        "Flags": "0x00",
        "SelSec": "0x1",
        "SelT1Key": "0x2",
        "SelKey": "0x0"
    },
    "partitionFileSystem": {
        "type": "Nested HFS0",
        "totals": {
            "directories": "3",
            "files": "8"
        },
        "tree": {
            "update": [],
            "normal": [],
            "secure": [
                {
                    "filename": "d410961e1dc9a4fde688ff19f80a4a3f.nca",
                    "extractpath": "secure/d410961e1dc9a4fde688ff19f80a4a3f.nca"
                },
                {
                    "filename": "1d57e359fdd5773e4a7030d4700ceece.nca",
                    "extractpath": "secure/1d57e359fdd5773e4a7030d4700ceece.nca"
                },
                {
                    "filename": "e1db2c894276b8918377f0b4a26d8070.nca",
                    "extractpath": "secure/e1db2c894276b8918377f0b4a26d8070.nca"
                },
                {
                    "filename": "b34f8b09c419320be1f2966c2c3a609a.cnmt.nca",
                    "extractpath": "secure/b34f8b09c419320be1f2966c2c3a609a.cnmt.nca"
                },
                {
                    "filename": "04b55d1660cf95359b636ba1170a668f.nca",
                    "extractpath": "secure/04b55d1660cf95359b636ba1170a668f.nca"
                },
                {
                    "filename": "db9912b1a244cd0eed73755c3cf42ca7.nca",
                    "extractpath": "secure/db9912b1a244cd0eed73755c3cf42ca7.nca"
                },
                {
                    "filename": "4ce4826de607d37626642db89151ac30.nca",
                    "extractpath": "secure/4ce4826de607d37626642db89151ac30.nca"
                },
                {
                    "filename": "8ad12697d849c2cd3a7b12cf45682b8e.nca",
                    "extractpath": "secure/8ad12697d849c2cd3a7b12cf45682b8e.nca"
                }
            ]
        }
    }
}

Default tool behavior on a NCA file

From

[NCA Header]
  Format Type:     NCA3
  Dist. Type:      Download
  Content Type:    Meta
  Key Generation:  11
  Sig. Generation: 0
  Kaek Index:      Application (0)
  Size:            0xe00
  ProgID:          0x01006b8014020000
  Content Index:   0
  SdkAddon Ver.:   12.0.0 (v201326592)

To

{
    "header": {
        "format": "NCA3",
        "distribution": "Download",
        "content": "Meta",
        "keyGeneration": 11,
        "signatureGeneration": 0,
        "kaekIndex": "Application (0)",
        "size": "0xe00",
        "programID": "0x01006b8014020000",
        "contentIndex": 0,
        "SDKAddonVersion": "12.0.0 (v201326592)"
    }
}