[extension] command.hashdup: Safe scan/trash vs approval-gated deletion for HashDup CLI

[mahdyarmonfared]

Contribution type

New Extension

Proposed or existing Extension ID

command.hashdup

Capability boundary

• Owned Scope: Syntax parsing and evidence classification for the hashdup CLI (cryptographic duplicate and zero-byte file finder).
• Out of Scope: Execution authority and final enforcement policy (delegated entirely to Guard runtime).
• Overlap: While command.filesystem owns generic rm / recursive unlinks, hashdup introduces a specific CLI dialect where --trash is non-destructive but --delete is destructive. We propose command.hashdup as the canonical identifier, with maintainer option to group under command.filesystem.

Command surface

• Executable: hashdup
• Dialect / Runtime: Node.js POSIX CLI (built with commander)
• Supported Operations: Positional directory path argument with options.
• Flags:
  • -a, --algo <sha256|md5> (Hash algorithm configuration)
  • -t, --trash <folder> (Reversible move to trash folder)
  • --delete (Permanent unrecoverable deletion)
  • --no-zero (Suppress reporting zero-byte empty files)
  • -h, --help, -V, --version
• Supported Versions: v1.0.0+

Destructive or sensitive examples

hashdup /workspace --delete
hashdup --delete /workspace
hashdup /data -a sha256 --delete

Safe counterparts

hashdup .
hashdup ./downloads --algo sha256
hashdup /workspace/assets -t ./backup_trash
hashdup /workspace/assets --trash ./backup_trash --no-zero
hashdup --help

Parser and composition edge cases

• Flag Reordering: Flag before or after positional path (hashdup --delete /path vs hashdup /path --delete).
• Paths with Spaces / Quoting: hashdup "My Documents/Project Files" --delete.
• Compound Commands & Wrappers:
  • Shell wrappers: sh -c 'hashdup /workspace --delete' or bash -c "..."
  • Iterators / Pipeline: find /data -maxdepth 1 -type d | xargs -I {} hashdup {} --delete
• Fail-Closed Malformed Input:
  • Unknown/ambiguous flags (hashdup /workspace --delete-mode, hashdup /workspace -x) must fail-closed to destructive review.
  • Suspicious or non-directory trash targets (hashdup /workspace --trash /dev/null) must default to destructive review.

Risk and authority model

• Action Classes:
  • filesystem.read.inspect for scan and read-only flags.
  • filesystem.mutate.reversible for --trash targeting valid directories.
  • filesystem.delete.unrecoverable for --delete.
• Default Mode: pause_for_approval on --delete or unrecognized options.
• Safer Alternatives: Suggest --trash <backup_folder> or dry-run scan instead of unrecoverable --delete.
• Authority Invariance: This extension produces evidence only; it cannot weaken existing command.filesystem or core protections.

Privacy and performance

• Privacy: CLI arguments only contain filesystem paths. Paths do not expose credentials; standard Guard workspace masking applies.
• Performance: Lightweight argument token matcher with O(N) flag inspection. Read-only scans are benign hot paths and bypass approval pauses.

Authoritative references

• Repository: https://github.com/mahdyarmonfared/hashdup-cli
• CLI Definition & Flags: https://github.com/mahdyarmonfared/hashdup-cli/blob/main/bin/hashdup.js

Readiness checklist

• I searched the Extension directory and existing issues for overlapping coverage.
• I removed secrets, credentials, private command history, and local paths from these examples.
• I can contribute or help validate destructive and safe-counterpart tests.

[zerocodefast]

Contribution type

New Extension

Proposed or existing Extension ID

command.hashdup

Capability boundary

• Owned Scope: Syntax parsing and evidence classification for the hashdup CLI (cryptographic duplicate and zero-byte file finder).
• Out of Scope: Execution authority and final enforcement policy (delegated entirely to Guard runtime).
• Overlap: While command.filesystem owns generic rm / recursive unlinks, hashdup introduces a specific CLI dialect where --trash is non-destructive but --delete is destructive. We propose command.hashdup as the canonical identifier, with maintainer option to group under command.filesystem.

Command surface

• Executable: hashdup

• Dialect / Runtime: Node.js POSIX CLI (built with commander)

• Supported Operations: Positional directory path argument with options.

• Flags:

  • -a, --algo <sha256|md5> (Hash algorithm configuration)
  • -t, --trash <folder> (Reversible move to trash folder)
  • --delete (Permanent unrecoverable deletion)
  • --no-zero (Suppress reporting zero-byte empty files)
  • -h, --help, -V, --version

• Supported Versions: v1.0.0+

Destructive or sensitive examples

hashdup /workspace --delete hashdup --delete /workspace hashdup /data -a sha256 --delete

Safe counterparts

hashdup . hashdup ./downloads --algo sha256 hashdup /workspace/assets -t ./backup_trash hashdup /workspace/assets --trash ./backup_trash --no-zero hashdup --help

Parser and composition edge cases

• Flag Reordering: Flag before or after positional path (hashdup --delete /path vs hashdup /path --delete).

• Paths with Spaces / Quoting: hashdup "My Documents/Project Files" --delete.

• Compound Commands & Wrappers:

  • Shell wrappers: sh -c 'hashdup /workspace --delete' or bash -c "..."
  • Iterators / Pipeline: find /data -maxdepth 1 -type d | xargs -I {} hashdup {} --delete

• Fail-Closed Malformed Input:

  • Unknown/ambiguous flags (hashdup /workspace --delete-mode, hashdup /workspace -x) must fail-closed to destructive review.
  • Suspicious or non-directory trash targets (hashdup /workspace --trash /dev/null) must default to destructive review.

Risk and authority model

• Action Classes:

  • filesystem.read.inspect for scan and read-only flags.
  • filesystem.mutate.reversible for --trash targeting valid directories.
  • filesystem.delete.unrecoverable for --delete.

• Default Mode: pause_for_approval on --delete or unrecognized options.

• Safer Alternatives: Suggest --trash <backup_folder> or dry-run scan instead of unrecoverable --delete.

• Authority Invariance: This extension produces evidence only; it cannot weaken existing command.filesystem or core protections.

Privacy and performance

• Privacy: CLI arguments only contain filesystem paths. Paths do not expose credentials; standard Guard workspace masking applies.
• Performance: Lightweight argument token matcher with O(N) flag inspection. Read-only scans are benign hot paths and bypass approval pauses.

Authoritative references

• Repository: https://github.com/mahdyarmonfared/hashdup-cli
• CLI Definition & Flags: https://github.com/mahdyarmonfared/hashdup-cli/blob/main/bin/hashdup.js

Readiness checklist

• I searched the Extension directory and existing issues for overlapping coverage.[x] I removed secrets, credentials, private command history, and local paths from these examples.[x] I can contribute or help validate destructive and safe-counterpart tests.

Sounds great! Looking forward to the PR.

[mahdyarmonfared]

Thanks @zerocodefast! Working on the extension parser and the fixture test suite right now. Will submit the PR shortly!