Skip to content

Commit fab8c4c

Browse files
lecodev-26lecodev-26
committed
Initial release of NEXUS-Q Tools workspace
0 parents  commit fab8c4c

87 files changed

Lines changed: 11327 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
name: Bug report
3+
about: Report a reproducible problem in a NEXUS-Q Tools command
4+
title: "[Bug]: "
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
## Affected tool and version
10+
11+
## Environment
12+
- OS / release:
13+
- Architecture:
14+
- Rust/Cargo version (if built from source):
15+
16+
## Command used
17+
Remove passwords, tokens, private keys, and sensitive paths before posting.
18+
19+
## Expected behavior
20+
21+
## Actual behavior
22+
23+
## Reproduction steps
24+
Use synthetic or non-sensitive test data only.
25+
26+
## Sanitized output and exit status
27+
28+
## Additional context

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
name: Feature request
3+
about: Suggest a focused improvement to an existing tool
4+
title: "[Feature]: "
5+
labels: enhancement
6+
assignees: ""
7+
---
8+
9+
## Problem to solve
10+
11+
## Proposed behavior
12+
13+
## Affected tool(s)
14+
15+
## Safety, privacy, or compatibility considerations
16+
17+
## Alternatives considered

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
## Summary
2+
3+
## Scope
4+
- [ ] One focused change
5+
- [ ] No changes to NEXUS-Q Core, SentinelFlow, or Nuvora
6+
- [ ] No unrelated refactoring
7+
8+
## Safety and compatibility
9+
- [ ] Inputs, outputs, and side effects are documented
10+
- [ ] No secrets or sensitive fixtures are included
11+
- [ ] New dependencies are justified
12+
- [ ] No developer-specific absolute paths
13+
14+
## Verification
15+
- [ ] cargo fmt --all --check
16+
- [ ] cargo test --workspace --offline
17+
- [ ] cargo build --workspace --offline
18+
- [ ] Relevant CLI smoke tests
19+
- [ ] Documentation audit
20+
21+
## Documentation
22+
- [ ] README / CLI reference / user guide updated as applicable
23+
- [ ] docs/CURRENT_STATE.md updated
24+
- [ ] docs/CHANGELOG.md updated
25+
- [ ] docs/DECISIONS.md updated if a design decision was confirmed
26+
27+
## Release impact
28+
- [ ] No version bump or publication is included
29+
- [ ] Any requested release/publish action has explicit maintainer authorization

‎.github/workflows/ci.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
pull_request:
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
workspace:
13+
name: Format, test, build, and audit docs
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Check out source
17+
uses: actions/checkout@v4
18+
19+
- name: Install stable Rust with rustfmt
20+
uses: dtolnay/rust-toolchain@stable
21+
with:
22+
components: rustfmt
23+
24+
- name: Check formatting
25+
run: cargo fmt --all --check
26+
27+
- name: Run workspace tests
28+
run: cargo test --workspace --locked
29+
30+
- name: Build workspace
31+
run: cargo build --workspace --locked
32+
33+
- name: Audit project documentation
34+
run: >-
35+
cargo run --locked -p nq-doc-audit --
36+
README.md CONTRIBUTING.md SECURITY.md SUPPORT.md CODE_OF_CONDUCT.md
37+
.github/ISSUE_TEMPLATE/bug_report.md
38+
.github/ISSUE_TEMPLATE/feature_request.md
39+
.github/PULL_REQUEST_TEMPLATE.md
40+
docs/ARCHITECTURE.md docs/PROJECT_OVERVIEW.md
41+
docs/CLI_REFERENCE.md docs/INSTALLATION.md docs/USER_GUIDE.md
42+
docs/SECURITY_MODEL.md docs/COMPATIBILITY.md docs/FAQ.md
43+
docs/CRATES_IO.md docs/CURRENT_STATE.md docs/CHANGELOG.md
44+
docs/DECISIONS.md docs/HANDOFF.md docs/ROADMAP.md
45+
docs/TOOL_IDEAS.md docs/TOOLS_IDEAS.md docs/WORKFLOW.md

‎.gitignore‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Rust / Cargo build artifacts
2+
/target/
3+
**/target/
4+
*.rs.bk
5+
*.pdb
6+
7+
# Environment files and local secrets
8+
.env
9+
.env.*
10+
!.env.example
11+
!.env.template
12+
*.pem
13+
*.key
14+
*.p12
15+
*.pfx
16+
*.keystore
17+
18+
# Local-only configuration
19+
.local/
20+
.local-config/
21+
*.local.toml
22+
23+
# Logs and temporary files
24+
*.log
25+
*.tmp
26+
*.temp
27+
*.swp
28+
*.swo
29+
*~
30+
31+
# Generated backup containers and backup copies
32+
*.nqsb
33+
*.bak
34+
*.backup
35+
36+
# Operating system files
37+
.DS_Store
38+
Thumbs.db
39+
desktop.ini
40+
41+
# IDE and editor state
42+
.idea/
43+
.vscode/
44+
45+
# Python tooling caches and virtual environments
46+
__pycache__/
47+
*.py[cod]
48+
.pytest_cache/
49+
.venv/
50+
venv/
51+
52+
# Coverage output
53+
coverage/
54+
lcov.info

‎AGENTS.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# AI Agent Instructions
2+
3+
## Mandatory startup procedure
4+
5+
- Read docs/CURRENT_STATE.md before any changes, then review README.md, PROJECT_OVERVIEW.md, ARCHITECTURE.md, ROADMAP.md, and WORKFLOW.md as needed.
6+
- Review DECISIONS.md and CHANGELOG.md before substantial changes.
7+
- Verify the real project files and environment; do not assume planned work is complete.
8+
9+
## Safety and scope boundaries
10+
11+
- Work only in ~/projects/nexusq-tools.
12+
- Do not modify the main NEXUS-Q engine or repository from this project.
13+
- Do not delete files, directories, branches, data, or projects without explicit authorization.
14+
- Do not touch SentinelFlow or Nuvora unless the user makes a specific request.
15+
- Do not push, publish releases, or publish crates without explicit authorization.
16+
- Never add secrets, tokens, private keys, credentials, or personal data to the repository.
17+
- Prefer small, reversible, verifiable changes. Explain risks before destructive operations.
18+
19+
## Working method
20+
21+
1. Identify the task and acceptance criteria before implementation.
22+
2. Inspect only what is necessary and ask about important missing decisions.
23+
3. Work in small steps; do not advance roadmap phases without agreement.
24+
4. Run appropriate tests and record exactly what was run and the result.
25+
5. Never claim a test, build, or publication succeeded unless verified.
26+
6. Separate confirmed, proposed, pending, and blocked information.
27+
7. Keep source code, CLI output, tests, and project documentation in English.
28+
8. Prefer clean code, minimal dependencies, and safe read-only defaults.
29+
30+
## Project continuity requirements
31+
32+
After each significant change:
33+
- Update docs/CURRENT_STATE.md with verified changes, tests, status, and the next action.
34+
- Add an entry to docs/CHANGELOG.md.
35+
- Record confirmed architecture or scope decisions in docs/DECISIONS.md.
36+
- Update docs/HANDOFF.md if work is interrupted.
37+
38+
Keep documents concise, accurate, and consistent. The verified project state—not chat history—is the source of truth.
39+
40+
## User's highest-priority rule
41+
42+
Before every change, read docs/CURRENT_STATE.md and compare it with the relevant real files. After each significant milestone, update CURRENT_STATE.md before declaring the work complete. Do not update it for every minor edit, but never begin a change without reading it or close a major milestone without updating it.

‎CITATION.cff‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
cff-version: 1.2.0
2+
message: "If you use NEXUS-Q Tools in research, software, or publications, please cite the release you used."
3+
title: "NEXUS-Q Tools"
4+
version: 0.1.0
5+
date-released: 2026-10-30
6+
license: MIT
7+
type: software
8+
authors:
9+
- name: "lecodev"
10+
email: "lecodev@outlook.es"
11+
abstract: >-
12+
A collection of independent command-line tools for the NEXUS-Q ecosystem.
13+
The tools use public NEXUS-Q Core APIs for supported engine operations
14+
and are maintained separately from the main engine.

‎CODE_OF_CONDUCT.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Code of Conduct
2+
3+
## Our commitment
4+
5+
NEXUS-Q Tools aims to be respectful, constructive, and technically rigorous. Participation should be welcoming regardless of background, identity, experience, or expertise.
6+
7+
## Expected behavior
8+
9+
- Be respectful, patient, and constructive.
10+
- Critique ideas and implementation details, not people.
11+
- Share technical feedback in good faith.
12+
- Respect privacy; do not publish private information.
13+
- Follow the security-reporting policy and avoid premature disclosure of exploitable vulnerabilities.
14+
- Respect project scope, safety requirements, and maintainer decisions.
15+
16+
## Unacceptable behavior
17+
18+
Harassment, discrimination, threats, personal attacks, doxxing, deliberate intimidation, and publication of private credentials or personal information are not acceptable.
19+
20+
## Enforcement
21+
22+
Maintainers may edit or remove unacceptable contributions and restrict participation when necessary to protect the community. Reports about conduct can be sent to [lecodev@outlook.es](mailto:lecodev@outlook.es). Do not use this address for vulnerability details; follow [SECURITY.md](SECURITY.md) instead.

‎CONTRIBUTING.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Contributing
2+
3+
Thank you for considering a contribution. NEXUS-Q Tools is a collection of independent Rust CLI crates that complement, but do not modify or replace, the NEXUS-Q Core engine.
4+
5+
## Before starting
6+
7+
1. Read README.md, docs/ARCHITECTURE.md, docs/WORKFLOW.md, and docs/CURRENT_STATE.md.
8+
2. Check docs/TOOL_IDEAS.md and docs/ROADMAP.md to avoid deferred work.
9+
3. Discuss substantial or security-sensitive changes before implementation.
10+
4. Do not modify the separate NEXUS-Q Core repository, SentinelFlow, or Nuvora.
11+
12+
## Development requirements
13+
14+
- Rust toolchain and Cargo.
15+
- Git for repository workflows.
16+
- Python 3 only when working on the crates.io publication helper.
17+
- Network access may be needed for initial dependency resolution.
18+
19+
## Project conventions
20+
21+
- Keep one independent executable crate per tool under crates/.
22+
- Use public NEXUS-Q Core APIs for supported engine operations. Do not reimplement cryptographic primitives.
23+
- Keep dependencies minimal and explain new dependencies.
24+
- Prefer read-only behavior, safe defaults, explicit outputs, and refusal to overwrite existing data.
25+
- Never log secrets or accept passwords as command-line arguments.
26+
- Keep source, tests, CLI output, and documentation in English.
27+
- Add tests for success, invalid input, failures, and safety boundaries.
28+
- Do not add developer-specific absolute paths.
29+
30+
## Validation
31+
32+
From the workspace root:
33+
34+
```sh
35+
cargo fmt --all --check
36+
cargo test --workspace --offline
37+
cargo build --workspace --offline
38+
```
39+
40+
Also run the affected CLI's --help and --version, representative success cases, and relevant failure/safety cases. Describe only behavior verified in the implementation.
41+
42+
## Documentation and pull requests
43+
44+
Update relevant user documentation, docs/CURRENT_STATE.md, and docs/CHANGELOG.md for significant changes. Record confirmed architectural decisions in docs/DECISIONS.md and update docs/HANDOFF.md when continuation context changes.
45+
46+
Keep changes focused. Explain motivation, behavior, compatibility impact, security implications, tests, and limitations. Never include credentials, private keys, real user vaults, or sensitive fixtures.
47+
48+
Do not bump versions, publish to crates.io, create releases, or push changes without explicit maintainer authorization.

0 commit comments

Comments
 (0)