Improve Handling of Multiple `.nuanced` Graphs and Provide Cleanup Guidance in Nuanced CLI

[aymannadeem]

Problem

Right now, if a user runs nuanced init multiple times in subdirectories of the same project (or accidentally), they can end up with multiple .nuanced/nuanced-graph.json files, for example:

.nuanced/nuanced-graph.json
json/.nuanced/nuanced-graph.json

When this happens, nuanced enrich fails or behaves inconsistently, and currently outputs:

Multiple Nuanced Graphs found in /path/to/repo:
  .nuanced/nuanced-graph.json
  json/.nuanced/nuanced-graph.json

However:

• The Nuanced docs implicitly assume users will run nuanced init at the repo root.
• Once multiple .nuanced directories exist, there is no CLI guidance on how to clean this up.
• The warning message clearly outlines the issue, and it's pretty clear what to do next, but if you're using automation to initialize a bunch of nuanced packages and there's some nesting, it can be difficult to dig all of the .nuanced (without doing find . -type d -name ".nuanced" or find . -type d -name ".nuanced" -exec rm -rf {} +)

Why this is confusing

• It’s easy to accidentally run nuanced init in subdirectories
• Once this happens, there is no clear recovery path or built-in tool to help
• Users may be blocked on nuanced enrich without understanding why

Proposal

1. Improve the warning message

When multiple .nuanced directories are found, update the warning to something like:

Multiple Nuanced Graphs found in /path/to/repo:
  .nuanced/nuanced-graph.json
  json/.nuanced/nuanced-graph.json

This will cause enrich to fail or behave inconsistently.
Please delete extra `.nuanced` directories so that only one remains.
Typically, you should keep `.nuanced/nuanced-graph.json` at the project root.

2. Add a CLI cleanup helper

Provide a CLI command such as:

nuanced cleanup

or maybe as part of init (?) not sure:

nuanced init cleanup

Which would:

• Detect and list all .nuanced/nuanced-graph.json files in the repo tree.
• Prompt the user to remove extras, or automatically remove them if confirmed.

Priority

It's just some nice UX polish that improves onboarding and reduces friction for new users. Def lower priority.

[ayush27316]

Hi,
First of all, Nuanced is an awesome project, and the overall design is easy to understand and work with.

I was wondering, is this project currently maintained? And is this issue open to contributions?

Thanks again!

[aymannadeem]

Hey @ayush27316, that's for the kind feedback! We’re happy to accept contributions on this issue.

Heads-up: we’re a small team and not actively prioritizing this area right now, so reviews may be slower than usual. If you’re interested in taking it:

• Comment here with your intended approach and we’ll assign the issue.
• Open a draft PR early so we can give lightweight feedback.
• Keep scope focused; include tests and brief docs/notes of the change.
• Consult contributing section of README.md.

If anything’s unclear, ask questions here and we’ll help as bandwidth allows.

[ayush27316]

Handling Duplicate .nuanced Directories

When running nuanced init in multiple locations within the same project, duplicate .nuanced directories can appear. This section outlines how to handle these cases.

Common Scenarios

1. Accidental Init in a Subdirectory (and User Catch It Early)

If the user mistakenly initializes in the wrong folder:

nuanced cleanup path/to/wrong/subdir

This removes the .nuanced directory at the given path.
Then return to the project root and re-initialize.

2.Initializing multiple times(Unnoticed)

If the user tries to initialize multiple times without realizing, the CLI will detect this:

$ nuanced init .
Warning: Found existing .nuanced directories in subdirectories:
  - ./src/utils/.nuanced
  - ./tests/.nuanced

These may conflict with the root-level initialization.
Would you like to clean them up? (y/N)

You’ll be prompted to review and remove the extras before proceeding.

Implementation Overview

nuanced cleanup <path>

• Removes a .nuanced directory at the given path (defaults to the current directory).
• Prints confirmation after cleanup.
• Handles missing paths or errors gracefully.

nuanced init <path>

• Before initializing, checks for existing .nuanced directories in subdirectories.

• Two possible detection strategies:

  1. Filesystem Scan – Walks the directory tree to locate .nuanced directories. Reliable but potentially slow in large projects.
  2. Metadata Store – Maintains a registry at $HOME/.nuanced to track project roots. Enables fast detection and can support richer tooling over time.

• On detecting duplicates, the CLI:

  • Warns the user.
  • Lists conflicting paths.
  • Prompts to remove extras before continuing.

Summary

• Use nuanced cleanup to remove stray .nuanced directories.
• The CLI detects duplicates on nuanced init and guides you through cleanup.
• Error handling and confirmation prompts make recovery from mistakes straightforward.

Next Steps

I’d like to move ahead with this feature. Between the two detection strategies, I’m inclined toward the metadata store since it can be reused for future functionality. Would you prefer starting with the metadata store approach, beginning with a simpler filesystem scan as an initial step, or focusing only on the nuanced cleanup command for now while improving error messages to guide users through resolving duplicates?