{"id":26931425,"url":"https://github.com/nikolainobadi/nnapp","last_synced_at":"2026-04-28T20:06:40.120Z","repository":{"id":285484564,"uuid":"955488541","full_name":"nikolainobadi/nnapp","owner":"nikolainobadi","description":"Utility to easily manage Xcode projects and Swift Packages and quickly launch them from command-line","archived":false,"fork":false,"pushed_at":"2025-04-01T01:05:37.000Z","size":130,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T02:22:34.209Z","etag":null,"topics":["automation","cli","command-line-tool","developer-experience","developer-tools","macos","productivity","swift","swiftdata","swiftpackage","xcode"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikolainobadi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-26T18:05:19.000Z","updated_at":"2025-04-01T01:05:40.000Z","dependencies_parsed_at":"2025-04-01T02:22:36.834Z","dependency_job_id":"40c9712b-bae2-4c19-abd3-08540eaa265e","html_url":"https://github.com/nikolainobadi/nnapp","commit_stats":null,"previous_names":["nikolainobadi/nnapp"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolainobadi%2Fnnapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolainobadi%2Fnnapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolainobadi%2Fnnapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolainobadi%2Fnnapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikolainobadi","download_url":"https://codeload.github.com/nikolainobadi/nnapp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246769914,"owners_count":20830771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli","command-line-tool","developer-experience","developer-tools","macos","productivity","swift","swiftdata","swiftpackage","xcode"],"created_at":"2025-04-02T07:17:23.761Z","updated_at":"2026-04-28T20:06:40.113Z","avatar_url":"https://github.com/nikolainobadi.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nnapp\n\n![Build Status](https://github.com/nikolainobadi/nnapp/actions/workflows/ci.yml/badge.svg)\n![Swift Version](https://badgen.net/badge/swift/6.0%2B/purple)\n![Platform](https://img.shields.io/badge/platform-macOS%2014-blue)\n![License](https://img.shields.io/badge/license-MIT-lightgray)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Category Commands](#category-commands)\n  - [Group Commands](#group-commands)\n  - [Project Commands](#project-commands)\n  - [Link Commands](#link-commands)\n  - [Opening Projects](#opening-projects)\n  - [Finder Commands](#finder-commands)\n  - [Evict Commands](#evict-commands)\n  - [Listing Resources](#listing-resources)\n- [Architecture Notes](#architecture-notes)\n- [Documentation](#documentation)\n- [Acknowledgments](#acknowledgments)\n- [About This Project](#about-this-project)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\n**nnapp** is a command-line utility designed to manage and launch Xcode projects and Swift packages with ease. It organizes your local development environment into **Categories**, **Groups**, and **Projects**, supporting both local file system operations and Git integrations.\n\nThink of it as a personalized project launcher with just enough metadata to keep your Swift workspace tidy and quickly accessible.\n\n**Stability Notice (0.9.0)**\n`nnapp` is functional and ready to use, but its features and API may evolve as it becomes more flexible and robust.\nCurrently, `nnapp` works with **iTerm** (opens a new tab) and **ShellBoss** (reuses the current tab via IPC); I'll add support for vanilla **Terminal** (and possibly others) for the official release.\nBreaking changes are possible before reaching 1.0.0.\nYour feedback and suggestions are welcome as the project continues to improve!\n\n\n## Features\n\n- Create, import, or remove **Categories**, **Groups**, and **Projects**\n- Browse for folders interactively (tree navigation) instead of typing paths for categories, groups, and projects\n- Launch Xcode or VSCode with optional terminal workflows\n- Open remote repositories or linked documentation instantly\n- Automatically clone projects from Git remotes if missing locally\n- **Branch status monitoring** - automatically checks if local projects are behind or diverged from remote, with desktop notifications\n- **Project eviction** — safely delete project folders while preserving metadata for easy re-cloning, with safety checks for dirty trees and unpushed commits\n- Manage custom quick-launch shortcuts and set main projects for groups\n- **Project links** - store and open named URLs (docs, analytics, repos, etc.) associated with projects\n- **Finder integration** - quickly open any category, group, or project folder in Finder\n- **ShellBoss integration** - when run from a ShellBoss tab, `nnapp open` `cd`s the current tab in place instead of spawning a new window\n- Stores metadata using `SwiftData` and `UserDefaults`\n- Shell integration via `NnShellKit`\n- Fully interactive CLI built on `ArgumentParser` and `SwiftPickerKit`\n\n---\n\n## Installation\n\nYou can install `nnapp` via [Homebrew](https://brew.sh) using the **nntools** tap:\n\n```sh\nbrew tap nikolainobadi/nntools\nbrew install nnapp\n```\n\n---\n\n## Usage\n\nAfter installation, run:\n\n```sh\nnnapp --help\n```\n\n### Category Commands\n\n- **Create a new category:**\n  ```sh\n  nnapp create category \"Platform\"\n  ```\n\n- **Import an existing folder as a category:**\n  ```sh\n  nnapp add category --path ~/dev/MyCategory\n  ```\n  Omit `--path` to browse interactively.\n\n- **Remove a category** (unregisters but doesn't delete the folder):\n  ```sh\n  nnapp remove category \"Platform\"\n  ```\n\n### Group Commands\n\n- **Create a new group:**\n  ```sh\n  nnapp create group \"Mobile\" --category \"Platform\"\n  ```\n\n- **Import an existing folder as a group:**\n  ```sh\n  nnapp add group --path ~/dev/MyGroup --category \"Platform\"\n  ```\n\n- **Remove a group:**\n  ```sh\n  nnapp remove group \"Mobile\"\n  ```\n\n- **Set a main project for a group:**\n  ```sh\n  nnapp set-main-project \"Mobile\"\n  ```\n  This synchronizes the project and group shortcuts for quick terminal access.\n\n### Project Commands\n\n- **Add a project:**\n  ```sh\n  nnapp add project --path ~/dev/MyApp --group Mobile\n  ```\n\n- **Add a project from Desktop:**\n  ```sh\n  nnapp add project --from-desktop --group Mobile\n  ```\n  Automatically filters to valid Xcode projects and Swift packages.\n\n- **Add a project with a shortcut:**\n  ```sh\n  nnapp add project --path ~/dev/MyApp --group Mobile --shortcut abc\n  ```\n\n- **Add a project as the main project:**\n  ```sh\n  nnapp add project --path ~/dev/MyApp --group Mobile --main-project\n  ```\n\n- **Remove a project:**\n  ```sh\n  nnapp remove project \"MyApp\"\n  ```\n\n- **Browse for a project folder** (interactive mode):\n  ```sh\n  nnapp add project --group Mobile\n  ```\n  If the project is not under the group folder, an interactive browser opens to pick any folder.\n\n### Link Commands\n\n- **Add a named link to a project:**\n  ```sh\n  nnapp add link \"Firebase\"\n  ```\n  Store reusable link names like \"Docs\", \"Analytics\", \"Repo\" for consistent metadata.\n\n- **Remove a link name:**\n  ```sh\n  nnapp remove link \"Firebase\"\n  ```\n\n- **List all saved link names:**\n  ```sh\n  nnapp list link\n  ```\n\n### Opening Projects\n\n- **Open project in Xcode with terminal** (default):\n  ```sh\n  nnapp open abc\n  ```\n\n- **Open in VSCode:**\n  ```sh\n  nnapp open abc -v\n  ```\n\n- **Open IDE only** (no terminal):\n  ```sh\n  nnapp open abc --no-terminal\n  ```\n\n- **Open terminal only:**\n  ```sh\n  nnapp open abc --terminal\n  ```\n\n- **Open remote repository:**\n  ```sh\n  nnapp open abc -r\n  ```\n\n- **Open project link:**\n  ```sh\n  nnapp open abc -l\n  ```\n  Select from saved links associated with the project.\n\n- **Open using group shortcut:**\n  ```sh\n  nnapp open xyz -g\n  ```\n  Opens the main project for the group with shortcut \"xyz\".\n\n### Finder Commands\n\n- **Open category folder in Finder:**\n  ```sh\n  nnapp finder category \"Platform\"\n  ```\n\n- **Open group folder in Finder:**\n  ```sh\n  nnapp finder group \"Mobile\"\n  ```\n\n- **Open project folder in Finder:**\n  ```sh\n  nnapp finder project \"MyApp\"\n  ```\n\n- **Browse and open any folder:**\n  ```sh\n  nnapp finder\n  ```\n\n### Evict Commands\n\n- **Evict a project by name:**\n  ```sh\n  nnapp evict \"MyApp\"\n  ```\n  Deletes the project folder but keeps metadata for easy re-cloning on next launch.\n\n- **Evict a project by shortcut:**\n  ```sh\n  nnapp evict --shortcut abc\n  ```\n\n- **Interactively select a project to evict:**\n  ```sh\n  nnapp evict\n  ```\n\nSafety checks run before deletion: blocks on dirty working trees, unpushed commits, or missing remotes.\n\n### Listing Resources\n\n- **List all registered entities** (interactive browser):\n  ```sh\n  nnapp list\n  ```\n\n- **List specific category details:**\n  ```sh\n  nnapp list category \"Platform\"\n  ```\n\n- **List specific group details:**\n  ```sh\n  nnapp list group \"Mobile\"\n  ```\n\n- **List specific project details:**\n  ```sh\n  nnapp list project \"MyApp\"\n  ```\n\n---\n\n## Architecture Notes\n\n- Shared logic lives in `CodeLaunchKit` (models, protocols, managers/services like `CategoryManager`, `GroupManager`, `ProjectManager`, `LaunchManager`, branch helpers), while CLI wiring and picker UX live in `nnapp` controllers.\n- Branch tooling (`BranchSyncChecker`, `BranchStatusNotifier`) is shared for reuse across platforms.\n- Interactive flows use `SwiftPickerKit`; shell/Git interactions are abstracted via `NnShellKit` and `NnGitKit`.\n- Persistence uses `SwiftData` for categories, groups, and projects; tree navigation via a shared folder browser.\n\n---\n\n## Documentation\n\nFor a complete command reference with all flags, options, and detailed explanations, see [Documentation.md](./docs/Documentation.md).\n\nThe formal documentation includes:\n- Comprehensive command reference with all flags and options\n- Detailed explanation of key concepts (main projects, links, branch monitoring)\n- Configuration and exit codes\n- Advanced usage patterns\n\n**Developer Documentation:**\n- Inline documentation is provided via comments and docstrings\n- Source code is organized for discoverability\n- See each command's `run()` method and its related `Controller` for usage flow\n\n---\n\n## Acknowledgments\n\n### Third-Party Libraries\n- [`ArgumentParser`](https://github.com/apple/swift-argument-parser) — CLI parsing\n- [`Files`](https://github.com/JohnSundell/Files) — filesystem handling\n\n### My Swift Packages\n- [`SwiftPickerKit`](https://github.com/nikolainobadi/SwiftPickerKit) — interactive prompts and tree navigation\n- [`NnShellKit`](https://github.com/nikolainobadi/NnShellKit) — shell abstraction\n- [`NnGitKit`](https://github.com/nikolainobadi/NnGitKit) — Git operations abstraction\n- [`NnSwiftDataKit`](https://github.com/nikolainobadi/NnSwiftDataKit) — shared SwiftData setup\n\n---\n\n## About This Project\n\n`nnapp` is what I built after getting annoyed one too many times with a messy desktop and forgotten rebases. I prefer the command line for version control and general navigation, so I wanted a way to launch Xcode or VS Code alongside a terminal without hunting through folders. Since I bounce between devices, the branch status monitoring keeps me from running into merge conflicts by alerting me when a project is behind its remote. I can link project-related websites and open them instantly with a simple command. It is a small tool that lets me be lazy in all the right ways so I can stay focused on building things.\n\n### Future Features\n\n- **Script command** — Define custom launch scripts for terminal workflows. (Temporarily disabled in v0.7.0, will be re-enabled soon)\n- **Terminal app support** — Expand beyond iTerm to support vanilla Terminal and potentially other terminal emulators\n\n---\n\n## Contributing\n\nContributions are welcome! If you'd like to improve a command, add new integrations, or fix bugs:\n\n1. Fork the repo\n2. Create a new branch\n3. Submit a PR with a clear description\n\nIssues and suggestions are also welcome via [GitHub Issues](https://github.com/nikolainobadi/nnapp/issues).\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikolainobadi%2Fnnapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikolainobadi%2Fnnapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikolainobadi%2Fnnapp/lists"}