diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml new file mode 100644 index 0000000..ef87d85 --- /dev/null +++ b/.github/workflows/wiki.yml @@ -0,0 +1,43 @@ +name: Publish wiki +on: + push: + branches: [main] + paths: + - "docs/wiki/**" + - ".github/workflows/wiki.yml" + workflow_dispatch: +permissions: + contents: read +concurrency: + group: wiki + cancel-in-progress: false +jobs: + # docs/wiki/ is the source of truth for the GitHub wiki. Pages are copied over and + # committed; pages that exist only in the wiki are left alone. + publish: + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Push pages to the wiki + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPOSITORY: ${{ github.repository }} + SHA: ${{ github.sha }} + run: | + git clone --depth 1 "https://x-access-token:${GITHUB_TOKEN}@github.com/${REPOSITORY}.wiki.git" wiki + cp docs/wiki/*.md wiki/ + cd wiki + git add -A + if git diff --cached --quiet; then + echo "Wiki is already up to date." + exit 0 + fi + git -c user.name="github-actions[bot]" \ + -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \ + commit -m "Sync wiki from ${REPOSITORY}@${SHA::7}" + git push diff --git a/docs/development.md b/docs/development.md index 84b2447..24636ba 100644 --- a/docs/development.md +++ b/docs/development.md @@ -63,6 +63,10 @@ Tauri writes `.deb` and `.rpm` packages under `src-tauri/target/release/bundle/` Release packages come from CI, which builds on Ubuntu 22.04 and declares a glibc 2.35 floor. A local `desktop:package` build on a newer distribution links against its newer glibc, so `scripts/verify-packages.py` correctly rejects it as a release candidate. See [Releases](releases.md#package-validation-and-distribution-ci). +## Wiki + +The [GitHub wiki](https://github.com/Commanderx-code/command-center/wiki) is published from `docs/wiki/`. Edit the pages there and open a pull request; after it merges, the `Publish wiki` workflow copies them to the wiki. Edits made directly in the wiki are overwritten the next time that page changes here. Page links use wiki names such as `[Settings](Settings)`, so they only resolve on the wiki itself. `Home.md`, `_Sidebar.md`, and `_Footer.md` are the landing page, sidebar, and footer. + ## Documentation screenshots The README screenshot is captured from the actual browser preview with sample data. Keep the preview notice visible and avoid publishing personal repository contents, credentials, or terminal transcripts. Refresh `docs/images/dashboard.jpg` when the dashboard changes materially. diff --git a/docs/wiki/Activity-and-Change-Timeline.md b/docs/wiki/Activity-and-Change-Timeline.md new file mode 100644 index 0000000..806a319 --- /dev/null +++ b/docs/wiki/Activity-and-Change-Timeline.md @@ -0,0 +1,45 @@ +# πŸ•’ Activity & Change Timeline + +> _What ran, what it printed, and what changed._ + +## Activity + +**Activity** is the history of every command Command Center has run: the last **100 jobs**, kept across restarts. The sidebar badge shows how many are running right now. + +Select a job to see: + +- its title, **status** (running, succeeded, failed, cancelled, timed out or interrupted), start and finish times, and **exit code**, +- the exact **command** and folder it ran in, +- its **output** (for background jobs, up to 2 MB per job; anything cut off is marked clearly). + +Actions on a job: + +| Button | When | +|---|---| +| **Stop job** | A background or embedded-terminal job is running. It stops the command and everything it started | +| **Terminal closed? Stop monitoring** | An external-terminal job whose terminal you've closed. Use it only once you're sure the command has ended | +| **Mark reviewed** | A failed job you've dealt with. It then leaves [Needs attention](Dashboard-and-Needs-Attention#needs-attention) | + +Interactive sessions (installers in the Terminal) record their result here, but not what was typed or shown. That stays in the terminal. See [How Commands Run](How-Commands-Run) for how jobs run, run side by side, and stop. + +If the app crashes or the computer shuts down during a job, that job is marked **interrupted** on the next start. Check what the command did before running it again. + +## Change timeline + +**Change timeline** answers *"what changed before this stopped working?"* It merges: + +- jobs from Activity: package updates, Git operations, backups, service actions, workflow and profile steps, and so on, +- configuration saves from the [Configuration](Configuration) page (each save keeps a backup of the previous file). + +**Search timeline** by title, result, category or folder, and filter with **All categories** or one category. **Refresh timeline** reloads it. + +A configuration entry means the file was saved (and the old one backed up). It doesn't mean the change was activated. For Home Manager-managed files, that happens when you apply Home Manager. + +> [!NOTE] +> The timeline only knows about changes made **through Command Center**. Changes from other apps or the command line don't appear. + +--- + +| | | +|:--|--:| +| [← 🩺 Health, Services & Inventory](Health-Services-and-Inventory) | [βš™οΈ Settings β†’](Settings) | diff --git a/docs/wiki/Backup-and-Restore.md b/docs/wiki/Backup-and-Restore.md new file mode 100644 index 0000000..b9d0d15 --- /dev/null +++ b/docs/wiki/Backup-and-Restore.md @@ -0,0 +1,108 @@ +# πŸ—„οΈ Backup & Restore + +> _Backups, snapshots, file history, restores, schedules and recovery tests._ + +**Backup & Restore** works with the backup setup you already have: your own backup scripts plus a [Restic](https://restic.net) repository. It runs your scripts, lets you browse and restore from snapshots, finds every saved version of a file, schedules backups, and can prove a restore actually works. + +Before you start, connect your helpers and repository in **Settings β†’ System integrations** (see [Getting Started](Getting-Started#2-finish-connecting-your-setup)). + +## Backup overview and readiness + +The top of the page shows: + +- **Where backups go** and whether the drive is connected, as reported by your **backup health helper**. If there's no report, the status shows as **unknown**, which doesn't mean disconnected. +- **When the last successful backup finished**, and whether it's overdue (the limit is set in Settings as *Backup freshness*). +- **Backup readiness**: whether your helpers exist and are executable, whether Restic is installed, and where credentials come from (KWallet, a password file or the environment). "Configured" isn't the same as "works". Use **Test repository access** to confirm that. + +Click **Refresh health** after plugging in a backup drive. + +## Running a backup + +- **Personal backup** runs your personal backup helper in the background. Output goes to Activity. +- **Full recovery backup** runs your full backup helper in a **terminal**, so it can ask for encryption passwords. + +Both buttons are disabled if the helper isn't set up, or if the health helper reports your backup drive disconnected. The app checks again when the job starts, and your scripts keep their own checks. + +## Checking the repository + +- **Test repository access** unlocks the repository with your configured credentials (this may prompt KWallet) and reads its configuration. Success means access works right now. +- **Check repository** runs Restic's integrity check on the repository's metadata. + +> [!TIP] +> Neither one proves that every file can be restored. For that, use [Recovery verification](#recovery-verification). + +## Browsing snapshots + +1. Click **Load snapshots** to list the latest 30. +2. Pick one and **Browse** its folders in the **Snapshot browser**. + +## Restoring files + +1. Choose the **Selected snapshot**. +2. Optionally set **Include path or pattern** to restore only some files, for example `/home/you/Documents/taxes`. Leave it blank to restore the whole snapshot. +3. Enter a **New destination folder** inside your home folder. It must not exist yet; its parent must. +4. Click **Review restore** and confirm. + +> [!NOTE] +> Restores **never overwrite** anything: files go into the new folder and are verified as they're written. Copy what you need back into place yourself. This recovers files; it isn't a full system or disk-image restore. + +## File history + +> [!NOTE] +> **New in 0.7.0** + +Deleted a file, or need yesterday's version? **File history** searches **every** snapshot for it: + +1. Type what you're looking for: + - a **name** such as `notes.md`, which matches it in any folder, + - an **exact path** such as `~/Documents/report.odt`, or + - a **pattern** with `*` and `?`, such as `*.kdbx`. +2. Tick **Ignore case** if you're not sure of the capitalization, then click **Search backups**. The review shows the exact Restic commands. The search only reads, but it goes through every snapshot, so large repositories can take a while. +3. Results are grouped by file path, newest first. Each saved copy shows: + - when it was backed up, with the snapshot ID and computer, + - the file's **modified** time and **size**, + - **First saved**, **Changed** (different size or modified time from the copy before) or **Same as previous**. + + **Show only versions that changed** (on by default) hides the identical copies, so you see just the real versions. +4. Click **Restore this version** on the one you want. The restore form below fills in that snapshot and the file's exact path. Enter a **New destination folder** and click **Review restore**. + +If a file is missing from newer backups of the same computer and folder, you'll see *"Not in the N newer snapshots… It may have been deleted or moved"*. The last row shows the final saved copy, ready to restore. + +Good to know: + +- "Changed" compares size and modified time, not the file contents. +- If a search matches thousands of files, it can't be shown. Search a more specific path. +- Restic reads `*`, `?` and `[` as pattern characters, so for a file whose name contains them, check the **Include path or pattern** before restoring. + +## Backup schedules & user timers + +This section lists your user **timers** (up to 100) with their next and last run, whether they're enabled, and the result of the service each one starts. **Enable** / **Disable** turn a timer on or off. **Service logs** shows the output of its last runs. + +### Scheduling automatic backups + +Under **Create or edit Command Center's backup schedule**, choose **hourly**, **daily** or **weekly (Sunday)** and a time, then **Review & save schedule**. The review shows the exact systemd timer and service files before anything is written. + +- It runs your **personal** backup helper, which must work unattended (no password prompts). +- Missed runs, for example while the computer was off, happen the next time your session starts. +- The app only writes its own two files (`command-center-backup.service` and `.timer`) and refuses to touch anything else. It keeps a `.bak` copy when changing its own schedule. +- If you already have another backup timer, disable one so backups don't run twice. +- Timers run while you're logged in. They don't wake a sleeping or powered-off computer. + +## Recovery verification + +A backup you've never restored from is a guess. Recovery verification proves one file comes back intact: + +1. Pick a small file (up to 100 MB) in your home folder that doesn't change often. In **Recovery verification**, choose it as the **Recorded file** and click **Record checksum**. +2. Run your normal backup so that exact version is in a snapshot. +3. **Load snapshots** and copy the new snapshot's ID into **Snapshot ID**. +4. Select the recorded baseline and click **Review recovery test**. + +The app restores just that file into a temporary folder, compares its checksum with the recorded one, and deletes the temporary copy. Your original file is never touched. The result shows under recent recovery results and in Activity. + +A pass proves that file can be recovered from that snapshot with your current credentials. It doesn't certify every file or every snapshot. If you edit the file later, record a new checksum. + +--- + +| | | +|:--|--:| +| [← πŸ” Workflows & Machine Profiles](Workflows-and-Machine-Profiles) | [πŸ”„ System Sync β†’](System-Sync) | diff --git a/docs/wiki/Configuration.md b/docs/wiki/Configuration.md new file mode 100644 index 0000000..0ed6e91 --- /dev/null +++ b/docs/wiki/Configuration.md @@ -0,0 +1,44 @@ +# πŸŽ›οΈ Configuration + +> _Ghostty and Fastfetch editors with preview, validation and history._ + +**Configuration** edits your **Ghostty** terminal and **Fastfetch** settings with visual controls, a live preview, validation and a full history. Pick the app from the **Application** dropdown. + +The editor always works on your editable **source** file (set in **Settings β†’ System integrations**). It never edits generated files in `/nix/store`. If Home Manager owns the live file, the page says so. Save your edits here, then use [System Sync](System-Sync) β†’ **Apply Home Manager** to activate them. + +## Editing + +You can edit in two ways, and they stay in sync: + +- **Controls:** form fields for common settings. + - *Ghostty:* font family and size, theme, window padding, background opacity, cursor style. Click **Apply controls to draft**. + - *Fastfetch:* logo source and type and the separator (**Apply logo & separator**), plus the **module** list: move modules up or down, remove them, or **Add module**. +- **Source configuration:** the raw file in a text editor, for anything the controls don't cover. + +Changes stay in a **draft** until you save. **Preview** shows roughly how the result will look: font, padding and opacity for Ghostty, the module list for Fastfetch. It's an illustration, not a real terminal. Fastfetch `command` modules are never run in the preview. + +## Saving + +1. **Validate** checks the draft. Ghostty uses its own `ghostty +validate-config`; Fastfetch checks the JSONC syntax and module structure. +2. **Review & save** shows the current and new content side by side. +3. On confirm, the app saves a backup of the current file, then writes the new one in a single step. + +> [!NOTE] +> If the file changed on disk after you loaded it (say, you edited it in another editor), saving stops and asks you to reload rather than overwrite that change. **Reload file** discards your draft and loads the file from disk again. + +Your edits keep everything else in the file: Ghostty keeps unrelated lines, and Fastfetch keeps comments and custom module options. + +## Configuration history + +**Configuration history** lists the last 100 saved versions for the selected app. + +- Select a version and click **Compare** to see it next to your current draft. +- **Review restore to draft** loads that version into the editor as a draft. Nothing is written until you **Review & save**. + +Every save also appears in the [Change timeline](Activity-and-Change-Timeline). + +--- + +| | | +|:--|--:| +| [← πŸ”„ System Sync](System-Sync) | [🩺 Health, Services & Inventory β†’](Health-Services-and-Inventory) | diff --git a/docs/wiki/Dashboard-and-Needs-Attention.md b/docs/wiki/Dashboard-and-Needs-Attention.md new file mode 100644 index 0000000..d112f99 --- /dev/null +++ b/docs/wiki/Dashboard-and-Needs-Attention.md @@ -0,0 +1,51 @@ +# πŸ“Š Dashboard & Needs Attention + +> _Your home screen, quick actions, and everything waiting for you._ + +## Dashboard + +The dashboard is your home screen (you can choose a different start page in **Settings β†’ General**). It shows: + +- **Status cards** for repositories, configuration, backups and system health, so you can see what's clean, what's changed, and what's overdue. +- **Quick actions** launchpad: **Refresh repos** re-reads every repository's status; **Run backup**, **Home Manager** and **Edit configs** open Backup & Restore, System Sync and Configuration. +- **Your quick actions:** your own buttons for commands you use often, such as `full-upgrade`, a backup or a build script. Each click still shows the command for review first. +- A **Make this machine yours** prompt until you've finished the setup wizard. +- Notices about setup imports, including an interrupted import that was rolled back (see [Moving to a New Machine](Moving-to-a-New-Machine)). + +### Adding quick actions + +Go to **Settings β†’ Custom quick actions β†’ Add action** (up to 20): + +| Field | Meaning | +|---|---| +| Name | The button label | +| Command | What to run | +| Working folder | Where it runs, for example `~` | +| Shell | **Direct** runs the program with its arguments and no shell tricks. **Fish** or **Bash** load your interactive shell setup, so your functions and aliases work. | +| Mode | **Background** (output in Activity, no input), **Embedded** (built-in terminal, can answer prompts) or **External** (your terminal app) | + +Example: a Fish action with command `full-upgrade`, working folder `~` and mode **Embedded** runs your upgrade function in the built-in terminal, where you can type your password. + +> [!WARNING] +> Commands are saved and shown in Activity as written, so don't put passwords in them. + +## Needs attention + +**Needs attention** gathers everything that wants action into one list: + +- Repositories with **uncommitted changes**, **unpushed commits**, or that are **behind** their remote +- **Failed jobs** you haven't reviewed yet (open them in Activity and click **Mark reviewed** once handled) +- **Backups** that are overdue or whose status is unavailable +- **Disks** at least 90% full +- **Failed services** + +Each item links to the page where you can deal with it. The sidebar badge shows how many items there are. + +> [!TIP] +> "Behind" and "ahead" counts come from your last **fetch**. Fetch a repository to refresh them. + +--- + +| | | +|:--|--:| +| [← πŸ” How Commands Run](How-Commands-Run) | [πŸ“‚ Repositories β†’](Repositories) | diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md new file mode 100644 index 0000000..5776823 --- /dev/null +++ b/docs/wiki/Getting-Started.md @@ -0,0 +1,74 @@ +# 🏁 Getting Started + +> _The setup wizard, connecting your tools, and your first action._ + +## 1. The setup wizard + +The first time you open Command Center, the **setup wizard** appears. You can reopen it any time from **Settings β†’ Setup & portability β†’ Setup wizard**. It has four steps, and nothing is saved until the last one: + +1. **Your workspace:** pick a display name and the folders where your Git repositories live (for example `~/github/projects`). Use absolute paths or paths starting with `~/`. +2. **Connect existing tools:** click **Detect existing setup**. The app looks for your dotfiles checkout (`~/.config/dotfiles/machine.json`), Home Manager profile, and backup helpers, and fills in any empty fields. Check what it found and correct anything that's wrong. +3. **Check this machine:** **Check prerequisites** confirms the paths exist and tools such as Git, Nix, Home Manager and Restic are installed. Nothing is installed here: use **Open Toolbox** for missing software. If you've saved a **machine profile**, **Inspect profile** shows which of its steps are ready (see [Workflows & Machine Profiles](Workflows-and-Machine-Profiles)). +4. **Review & save.** Saving only stores your connections. It doesn't run installers or apply Home Manager. + +> [!TIP] +> Setting up a second machine? Choose **Import an existing setup…** in step 1 instead. See [Moving to a New Machine](Moving-to-a-New-Machine). + +## 2. Finish connecting your setup + +Open **Settings β†’ System integrations** to review everything the wizard didn't cover: + +- **Dotfiles repository** and **Home Manager profile** (the flake output name, such as `commander`). +- **Backup helpers:** your personal backup script, full backup script, and **backup health helper** (a script that prints JSON; it runs automatically for status checks, so point it only at a script you trust). +- **Restic repository** and how to unlock it: a **KWallet** entry, a **password file**, or credentials already in your environment. The app never stores your password itself. +- **Ghostty** and **Fastfetch** source files: the editable files in your dotfiles, not the generated copies in `/nix/store`. + +Click **Check availability** to test the values before saving. See [Settings](Settings) for every option. + +## 3. Find your way around + +The left sidebar lists every page: + +| Page | What's there | +|---|---| +| Dashboard | Status cards and your quick actions | +| Needs attention | Everything waiting for you | +| Repositories | All your Git projects | +| Toolbox Β· Terminal | Installers and their interactive sessions | +| Workflows | Saved routines and machine profiles | +| System Sync | Dotfiles and Home Manager | +| Backup & Restore | Backups, snapshots, restores, schedules | +| Configuration | Ghostty and Fastfetch editors | +| System Health Β· Services Β· System inventory | Machine status | +| Activity Β· Change timeline | What ran, and what changed | +| Settings | Everything configurable | + +### Keyboard shortcuts + +| Keys | Action | +|---|---| +| **Ctrl+K** | Command palette: jump to any page, repository or quick action | +| **↑ / ↓**, **Home / End** (in the sidebar) | Move between pages; **Enter** opens one | +| **Tab** at the top of the window | Shows **Skip to main content** | +| **Esc** | Close a dialog or clear the settings search | + +The app follows your system's reduced-motion setting. + +## 4. Try your first action + +1. Open **Repositories** and click **Workspace** on any project. +2. Click **Fetch**. A review window shows the exact `git fetch` command and folder. +3. Click **Run action**. The result appears below the buttons and in **Activity**. + +> [!NOTE] +> That review-then-run pattern works the same everywhere in the app. [How Commands Run](How-Commands-Run) explains it in full. + +## The system tray + +Command Center adds a tray icon (on desktops that support one) to show, hide or quit the window. Its tooltip shows running tasks. Closing the window quits the app. Use **Hide window** in the tray menu to keep it running in the background. + +--- + +| | | +|:--|--:| +| [← πŸ“¦ Installation](Installation) | [πŸ” How Commands Run β†’](How-Commands-Run) | diff --git a/docs/wiki/Health-Services-and-Inventory.md b/docs/wiki/Health-Services-and-Inventory.md new file mode 100644 index 0000000..dc36171 --- /dev/null +++ b/docs/wiki/Health-Services-and-Inventory.md @@ -0,0 +1,58 @@ +# 🩺 Health, Services & Inventory + +> _Disks, services, updates and installed tools._ + +Three pages that tell you how the machine is doing. + +## System Health + +A quick check-up, refreshed with **Refresh health**: + +- **Disk usage** for `/` and your home folder. Disks at 90% or more also appear in [Needs attention](Dashboard-and-Needs-Attention#needs-attention). +- **Failed services**, both user and system. +- **Package updates** (Arch-based systems) from the local package database. This doesn't download a fresh package list. Use **Toolbox β†’ Toolbox Updates** for a fresh check (see [Toolbox & Terminal](Toolbox-and-Terminal#toolbox-updates)). +- **Battery** status on laptops. +- **Installed tools:** which of Git, Nix, Home Manager, Restic, Ghostty, Fastfetch and others are installed. +- **Backup freshness** from your backup health helper. +- **Recovery readiness:** whether the pieces you'd need after a disaster are in place (dotfiles checkout, Home Manager flake, backup drive, encrypted recovery files, recovery instructions). It checks that these exist; it doesn't test decryption or a full restore. + +> [!NOTE] +> Health checks only read information. They never unlock your backup repository. + +## Services + +**Services** lists the systemd **user** and **system** services and timers on the machine. + +- **Filter** by state (**All states**, **Active**, **Inactive**, **Failed**, **Not loaded**) and search by name or description. **Enabled but inactive Β· review** finds services set to start at boot that aren't running. That's often normal (timers, on-demand services), but worth a look. +- Select a service to see its **properties**, what depends on it, and its **latest 100 log lines**. +- **User services** can be **started**, **stopped** or **restarted** (reviewed like any command). **System services** are view-only. Manage those from a terminal with `sudo`. + +### Service cleanup + +Expand **Service cleanup** and click **Export cleanup helper** to save a script to Downloads. The app never runs it. Run it yourself: + +```sh +bash ~/Downloads/service-cleanup.sh user # audit your user services +bash ~/Downloads/service-cleanup.sh system # audit system services +``` + +To disable a service you've decided you don't need: + +```sh +bash ~/Downloads/service-cleanup.sh user --disable NAME.service +sudo bash ~/Downloads/service-cleanup.sh system --disable NAME.service +``` + +The helper shows the service's details, what depends on it and how to re-enable it, then asks you to type its full name to confirm. It only **disables** loaded, enabled, inactive services. It never deletes, masks, uninstalls or stops anything. Failed services need investigating, not cleanup. + +## System inventory + +**System inventory** collects a summary of the machine: OS and kernel, CPU, memory, storage and disk usage, and the versions of installed tools. Anything missing or slow to answer shows as unavailable. + +**Export displayed report** saves it as JSON in Downloads, which is handy for bug reports or comparing machines. It can include mount paths and configuration details, so read it before sharing. Nothing is uploaded. + +--- + +| | | +|:--|--:| +| [← πŸŽ›οΈ Configuration](Configuration) | [πŸ•’ Activity & Change Timeline β†’](Activity-and-Change-Timeline) | diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..f76a717 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,100 @@ +
+ +Command Center icon + +# Command Center Guide + +### Your Linux workstation, under control. + +Your Git repositories, the Commander Toolbox installers, dotfiles and Home Manager, backups and restores,
+configuration files, services, and system health, in one desktop app. + +**Runs locally as your normal user Β· No account Β· No cloud service Β· No telemetry** + +
+ +Command Center dashboard + +
+ +> [!NOTE] +> This wiki is written for **Command Center 0.7.1**. Check your version under **Settings β†’ About & updates**. + +## πŸ” The one rule: you see every command first + +Command Center never runs anything behind your back. Every action that changes your system opens a **review** first. The review shows the exact command and the folder it runs in, and nothing starts until you confirm. Results are kept in **Activity**. + +> [!TIP] +> Read [How Commands Run](How-Commands-Run) once. It explains the review, running jobs side by side, stopping jobs, and what the app does on its own (only read-only checks). + +## 🏁 Quick start + +1. πŸ“¦ [Install Command Center](Installation) and launch it from your application menu. +2. πŸ§™ Follow the **setup wizard**: choose your repository folders, detect your dotfiles, Home Manager and backup helpers, then check what's installed. See [Getting Started](Getting-Started). +3. πŸ“‚ Open **Repositories** to see every project and its status. +4. 🧰 Open **Toolbox**, pick a tool and choose **Review & run**. +5. ⌨️ Press **Ctrl+K** anywhere to jump to a page, repository or quick action. + +## πŸ—ΊοΈ What can it do? + + + + + + + + + + + + + + + + + + + + + + +
+

πŸ“Š Dashboard & Needs Attention

+ See repositories, backups, configuration and health at a glance, launch your own quick actions, and see everything that wants your action in one list. + 		+

πŸ“‚ Repositories

+ Find all your Git projects, review changes, stage, commit, branch, stash, fetch/pull/push, and run project tasks. +
+

🧰 Toolbox & Terminal

+ Browse and run the 215 Commander Toolbox installers and your own personal tools, and answer their prompts inside the app. + 		+

πŸ” Workflows & Machine Profiles

+ Save multi-step maintenance routines and new-machine setup recipes. +
+

πŸ—„οΈ Backup & Restore

+ Run backups, browse Restic snapshots, find every saved version of a file, restore files, schedule backups, and prove recovery works. + 		+

πŸ”„ System Sync

+ Review dotfiles changes, then build and apply Home Manager. +
+

πŸŽ›οΈ Configuration

+ Edit Ghostty and Fastfetch with visual controls, a preview, validation and history. + 		+

🩺 Health, Services & Inventory

+ Check disks, failed services, updates, and installed tools; manage user services. +
+

πŸ•’ Activity & Change Timeline

+ See every command's output and result, and search what changed and when. + 		+

βš™οΈ Settings

+ Connect your setup, customize the app, and move it to another machine. +
+ +## πŸ“š More + +| | | +| ---------------------------------------------------------------------------- | --------------------------------------------------------------- | +| 🚚 [Moving to a New Machine](Moving-to-a-New-Machine) | Carry your whole setup to another computer with a setup bundle. | +| πŸ”’ [Your Data & Privacy](Your-Data-and-Privacy) | What's stored, where, and what the app never does on its own. | +| πŸ›Ÿ [Troubleshooting & FAQ](Troubleshooting-and-FAQ) | Fixes for common problems. | +| πŸ› [Open an issue](https://github.com/Commanderx-code/command-center/issues) | Found a bug or have an idea? Let us know. | diff --git a/docs/wiki/How-Commands-Run.md b/docs/wiki/How-Commands-Run.md new file mode 100644 index 0000000..8fc8e08 --- /dev/null +++ b/docs/wiki/How-Commands-Run.md @@ -0,0 +1,71 @@ +# πŸ” How Commands Run + +> _Review, run, watch and stop: how every action works._ + +Everything in Command Center that changes your system follows the same pattern. + +## 1. Review + +Clicking an action (Fetch, Review & commit, Run a Toolbox installer, Start a backup…) opens a **review** window with: + +- a title and a plain-language explanation, +- the **working directory**, +- the **exact command and arguments** that will run. + +**Cancel** runs nothing. **Run action** (or the button's specific wording) starts it. Previews expire after 5 minutes; after that, click the action again. + +Just before starting, the app rebuilds the command from your current settings. If anything changed since you opened the review, such as a setting, a path or a branch, it refuses with *"Settings changed; review the action again"* instead of running something different from what you approved. + +## 2. Run + +Commands run as **your normal user**, never as root. Where a job runs depends on what it needs: + +| Mode | Used for | Input | Output | +|---|---|---|---| +| **Background** | Git operations, backups, checks, most tasks | None | Streamed into **Activity** (up to 2 MB per job) | +| **Embedded terminal** | Installers and anything that asks questions | Type in the **Terminal** page, including passwords | Shown on screen only, never saved to Activity | +| **External terminal** | Same, in your own terminal app | In that terminal | Stays in that terminal | + +Password prompts (for example from `sudo` inside an installer) come from the command itself and are answered in the terminal. Command Center never asks for or stores your passwords. + +## 3. Watch and stop + +**Activity** lists every job with its status, exit code and output. Select a running job and click **Stop job** to cancel it. The app stops the command and everything it started. + +> [!CAUTION] +> A stopped command may already have made partial changes, so check its output before retrying. + +For jobs in an **external terminal**, stop them in that terminal. If you closed the terminal without finishing, use **Terminal closed? Stop monitoring** once you're sure the command has ended. + +## Running several jobs + +Jobs run at the same time unless they would get in each other's way: + +- **Repository jobs** (fetch, pull, push, staging, commits, branches, stashes) and **project tasks** run in parallel as long as they're in **different repositories**. +- **Workstation tasks** are everything else: Toolbox installers, backups and restores, Home Manager, updates, workflows, personal tools and quick actions. They run **one at a time**, but alongside repository jobs. +- Two jobs never run in the **same folder** at once. +- The **embedded terminal** holds one interactive session at a time. External-terminal jobs don't count against it. + +If a job has to wait, the app tells you which one it's waiting for, for example *"Wait for "npm Β· build" to finish. It uses the same folder."* The tray tooltip shows how many jobs are running. + +## What runs without asking? + +Only **read-only checks**: + +- Git status, diffs and history for your repositories. These run with all repository-controlled programs (hooks, filters, external diff tools, signature checks) switched off, so opening or scanning a repository can never run code from it. +- Disk space, failed services and cached package updates. +- Your configured **backup health helper**, which reports backup status. It's the one script you configure that the app runs by itself, so only point it at a script you trust. Imported settings can never change it. +- File and tool presence checks, which look at files but don't execute them. + +> [!IMPORTANT] +> Nothing you **import** (settings, setup bundles, workflows) ever runs automatically. Imported commands still go through review each time. + +## Closing the app while jobs run + +Closing the window is blocked while a job is running. The app takes you to Activity so you can wait or stop the job. If the app or computer crashes mid-job, that job shows as **interrupted** on the next start. Check the command's effects before retrying it. + +--- + +| | | +|:--|--:| +| [← 🏁 Getting Started](Getting-Started) | [πŸ“Š Dashboard & Needs Attention β†’](Dashboard-and-Needs-Attention) | diff --git a/docs/wiki/Installation.md b/docs/wiki/Installation.md new file mode 100644 index 0000000..6160c9b --- /dev/null +++ b/docs/wiki/Installation.md @@ -0,0 +1,78 @@ +# πŸ“¦ Installation + +> _Download, install, verify and update Command Center._ + +Command Center runs on **64-bit Linux (x86_64)**. Download packages from the [latest release](https://github.com/Commanderx-code/command-center/releases/latest). + +| Your system | Download | Install | +|---|---|---| +| Debian 12+, Ubuntu 22.04+ and derivatives | `command-center__amd64.deb` | `sudo apt install ./command-center_0.7.1_amd64.deb` | +| Fedora and other RPM systems | `command-center--1.x86_64.rpm` | `sudo dnf install ./command-center-0.7.1-1.x86_64.rpm` | +| Arch, Garuda, EndeavourOS, Manjaro | `command-center--1-x86_64.pkg.tar.zst` | `sudo pacman -U ./command-center-0.7.1-1-x86_64.pkg.tar.zst` | + +The `.deb` and `.rpm` need **glibc 2.35 or newer, GTK 3, WebKitGTK 4.1** and the AppIndicator library. The package manager installs these for you. Every release is install- and launch-tested on Ubuntu 22.04, Debian 12, Ubuntu 24.04, Fedora 43 and current Arch. + +> [!TIP] +> The Arch package is built against current Arch libraries, so update your system (`sudo pacman -Syu`) before installing it. + +After installing, open **Command Center** from your application menu. + +> [!WARNING] +> Always run Command Center as your normal user, never with `sudo`. + +## Check your download (recommended) + +Each release has a `SHA256SUMS` file. Put it in the same folder as your download and run: + +```sh +sha256sum --check --ignore-missing SHA256SUMS +``` + +Your package should report `OK`. + +## Optional extras + +| Install | To get | +|---|---| +| `libnotify` (`notify-send`) | Desktop notifications | +| `restic` 0.17 or newer | Snapshot browsing, file history, restores and recovery tests | +| `fish` | Fish-shell quick actions and tasks | +| `git` | Repository features (almost certainly installed already) | + +> [!NOTE] +> Missing tools never break the app. The features that need them show as unavailable. + +## Updating + +- **Package installs:** download the new release and install it the same way. Your settings and data are kept. +- **Checking for updates:** **Settings β†’ About & updates β†’ Check for releases** asks GitHub for the latest release and shows its notes. The app only contacts GitHub when you click this. +- **Source installs:** in the same section, **Export source updater** saves a helper script to Downloads. Close the app and run the command it shows, for example `bash ~/Downloads/update-desktop.sh v0.7.1`. It builds the release in a temporary folder, runs the tests, and installs only if they pass. The previous binary is kept as `~/.local/bin/command-center.previous` in case you need to roll back. + +## Building from source + +On Arch/Garuda, install the build dependencies: + +```sh +sudo pacman -S --needed webkit2gtk-4.1 base-devel curl wget file openssl appmenu-gtk-module librsvg nodejs npm rust git +``` + +Then: + +```sh +git clone https://github.com/Commanderx-code/command-center.git +cd command-center +npm ci +npm run desktop:install # builds and installs to ~/.local/bin for your user +``` + +`npm run dev` starts a browser preview with sample data at `http://127.0.0.1:4173`. It's handy for looking around, but it can't run commands or read your real files. The full developer guide is in [docs/development.md](https://github.com/Commanderx-code/command-center/blob/main/docs/development.md). + +## Uninstalling + +Remove the package with your package manager (`sudo apt remove command-center`, `sudo dnf remove command-center` or `sudo pacman -R command-center`). Your settings and history stay in your home folder. See [Your Data & Privacy](Your-Data-and-Privacy) to remove them too. + +--- + +| | | +|:--|--:| +| [← 🏠 Home](Home) | [🏁 Getting Started β†’](Getting-Started) | diff --git a/docs/wiki/Moving-to-a-New-Machine.md b/docs/wiki/Moving-to-a-New-Machine.md new file mode 100644 index 0000000..6578654 --- /dev/null +++ b/docs/wiki/Moving-to-a-New-Machine.md @@ -0,0 +1,57 @@ +# 🚚 Moving to a New Machine + +> _Carry your whole setup to another computer._ + +A **setup bundle** is a single file with your whole Command Center setup, ready to import on another computer. + +## What's in a bundle + +βœ… Included: preferences, repository scan folders and the list of known repositories, project favorites, groups, launch profiles, tasks and linked services, maintenance workflows, machine profiles, personal tools, quick actions, notification preferences, and Toolbox favorites. + +❌ Not included: your repositories' contents, backups, password files, KWallet names, activity history, recovery checksums, the contents of your config files, and remote Restic addresses (they can contain passwords). + +> [!WARNING] +> Commands you've saved (quick actions, tasks, tools, workflow inputs) are included **exactly as written**. Look them over for anything private before sharing the file. + +## On the old machine: export + +1. **Settings β†’ Setup & portability β†’ Export setup bundle…** +2. Read through the preview. It's the complete file. +3. Click **Export bundle**. It's saved to Downloads as `command-center-setup-.json`. + +## On the new machine: import + +1. Install Command Center, then choose **Import setup bundle…** in Settings (or **Import an existing setup…** in the setup wizard) and pick the file. +2. Check **Home folder on this machine**. Paths from the old machine (`/home/old-name/…` and `~/…`) are rewritten to this home folder. Other paths, URLs and anything inside command text stay as they are, so check them. +3. Choose an **Import method**: + - **Merge** (the default) keeps everything already on this machine and adds what's new: new workflows, profiles, tools, quick actions and projects, new scan folders and favorites, and integration paths that are empty here. If the bundle has a *different* version of something that already exists, the local one wins, and it's listed under **Already on this machine and kept unchanged**. Your preferences (theme, editor, and so on) aren't changed. + - **Replace** swaps this machine's saved setup for the bundle's. +4. Review the preview. It's exactly what will be saved. Tick the confirmation box and click **Import setup & reload**. + +The app reloads with your setup. + +> [!IMPORTANT] +> **Nothing from the bundle runs**: every command still goes through review when you use it. + +Repositories that aren't on this machine yet are remembered, not cloned. Add **Clone repository** steps to a [machine profile](Workflows-and-Machine-Profiles#machine-profiles) to fetch them. + +These always stay as they are on this machine: your password file, KWallet settings and **backup health helper**. Set those in Settings after importing. + +## If something goes wrong + +- **Before importing**, the app saves a private backup of the files it will replace (in its data folder, under `setup-backups/`). Settings shows the path after the reload. +- **If writing fails** partway, the files already written are rolled back straight away. +- **If the app or computer stops mid-import**, the next launch automatically restores the previous setup before the window opens, and the dashboard tells you. Import again when you're ready. +- If automatic recovery can't finish, the dashboard explains why and points to the backup file for manual recovery. + +Imports are refused while a job is running, if the file isn't a Command Center bundle, if it's over 2 MB, or if your setup changed after you previewed it. In that last case, just preview again. + +## Only moving preferences? + +**Settings β†’ Export saved settings** / **Import settings…** transfers only preferences and quick actions. See [Settings](Settings#export-and-import-settings). + +--- + +| | | +|:--|--:| +| [← βš™οΈ Settings](Settings) | [πŸ”’ Your Data & Privacy β†’](Your-Data-and-Privacy) | diff --git a/docs/wiki/Repositories.md b/docs/wiki/Repositories.md new file mode 100644 index 0000000..411608b --- /dev/null +++ b/docs/wiki/Repositories.md @@ -0,0 +1,89 @@ +# πŸ“‚ Repositories + +> _Everyday Git work across all your projects._ + +**Repositories** finds every Git project in your scan folders and lets you do everyday Git work without leaving the app. Every Git command is shown for review before it runs. + +## Finding your projects + +Command Center scans the folders listed in **Settings β†’ Repositories** (for example `~/github/projects` and `~/dotfiles`), down to the configured **scan depth**. Each project shows its branch, number of changed files, and how far it is **ahead** of or **behind** its remote. + +- **Search** by name, path or branch. +- **Filter** by changed, clean, ahead or behind, by **group**, or by **β˜† Favorites**. +- **Sort** by name (A–Z or Z–A) or **Needs attention first**. +- Switch between **cards** and **list** layout, or hide paths, in **Settings β†’ Repositories**. +- Click **↻** (Refresh repositories) after cloning something new, or set automatic refresh in Settings. + +> [!TIP] +> Ahead/behind counts reflect your last **fetch**. + +## Project Workspace + +Click **Workspace** on a repository to open its page. It has: + +### Remote: Fetch, Pull, Push + +- **Fetch** downloads what's new on the remote without changing your files. +- **Pull** updates your branch, but only as a fast-forward and only when you have no uncommitted changes, so it never creates a surprise merge. +- **Push** sends your commits to the branch's upstream. It never force-pushes and never pushes tags automatically. + +Authentication uses your existing Git credentials or SSH keys. If they need interactive input (for example an SSH passphrase), the job fails with a clear error instead of hanging; use the repository **Terminal** button for that. + +### Review changes + +Click any file to see its **diff**, then switch between **Staged** (what will be committed) and **Unstaged** (what's only on disk). **All tracked files** shows everything together. Additions and deletions are colored; binary files get a summary; very large diffs are marked as truncated. + +### Stage & commit + +1. Tick files and click **Stage selected**, or **Stage all** (includes new and deleted files, respects `.gitignore`). +2. **Unstage selected** takes files out of the next commit without touching your edits. +3. Check the **Staged diff**, write a **Commit message**, and click **Review & commit**. + +Just before committing, the app checks that the staged files, branch and last commit haven't changed since you reviewed them. Your normal Git hooks, identity and commit signing still apply. Committing is local; click **Push** to publish. + +Your draft message is kept if a commit fails or you cancel. Merge conflicts, rebases and cherry-picks in progress need to be finished in your editor or terminal. + +### Branches + +- **Switch branch** or **Create & switch**. Both need a clean working tree, so commit or stash first. +- **Review & publish branch** pushes a new local branch to a remote you choose and sets it as the upstream, so later pushes use the plain **Push** button. + +### Stash unfinished work + +**Review & stash** saves your changes (optionally **Include new (untracked) files**) and cleans the working tree. **Review & restore stash** brings them back and keeps the stash as a safety copy. + +### Recent commits + +The latest commits on the current branch. + +## Project tasks + +Save the commands you run in a project (build, test, dev server…) as one-click **tasks**: + +- **Detect project tasks** reads `package.json` (build, test, dev, lint, check, start) and `Cargo.toml` (build, test, check, run) and suggests tasks. Detection only reads the files and never runs your scripts. Add the suggestions you want. +- **Add task** creates your own: a name, command, shell (Direct, Fish or Bash) and mode (Background, Embedded or External). + +Tasks always run in the repository's root folder and go through review. Long-running tasks such as dev servers keep going until you stop them in **Activity**. Tasks in **different** repositories can run at the same time. See [How Commands Run](How-Commands-Run#running-several-jobs). + +## Related services + +Link a user or system **service** or **timer** to the project (for example the database it uses) to see its status and recent log lines right there. Linking only lets you look; to start or stop it, use the **Services** page. + +## Organization & launch profile + +- Mark a project as a **favorite** and put it in a **group** (for example "Work" or "Homelab"). +- Add a **documentation link**. +- Choose what **Open workspace** / **Launch profile** opens: your **editor**, a **terminal** in the project folder, and/or the **documentation**. Editor and terminal are chosen in **Settings β†’ Applications**. + +## Good to know + +- **Scanning a repository is always safe.** Status and diffs run with hooks, filters, external diff tools and signature checks turned off, so a repository you downloaded can't run code just by being opened. Side effect: files that a Git filter (such as Git LFS) normally rewrites may show as changed in previews. Check those in the terminal. +- Changes inside **submodules** aren't listed; a changed submodule commit is. Open the submodule itself to see its files. +- **Partial clones** with missing objects need a `git fetch` in the terminal before they can be inspected. +- Avoid running other Git tools on the same repository while an app operation is running. + +--- + +| | | +|:--|--:| +| [← πŸ“Š Dashboard & Needs Attention](Dashboard-and-Needs-Attention) | [🧰 Toolbox & Terminal β†’](Toolbox-and-Terminal) | diff --git a/docs/wiki/Settings.md b/docs/wiki/Settings.md new file mode 100644 index 0000000..329333b --- /dev/null +++ b/docs/wiki/Settings.md @@ -0,0 +1,86 @@ +# βš™οΈ Settings + +> _Everything configurable, section by section._ + +**Settings** holds everything configurable. Use **Search settings** at the top to filter by keyword (try "terminal", "theme" or "backup"), or jump with the section links. + +> [!NOTE] +> Changes are a **draft** until you click **Save settings**. **Discard changes** returns to what's saved, and **Reset to defaults** starts over. Appearance changes preview as you edit. + +## 01 Β· General + +| Setting | What it does | +|---|---| +| Display name | Used in your greeting | +| Start page | The page Command Center opens on: any page, including Toolbox, Activity or Needs attention | + +## 02 Β· Applications + +| Setting | What it does | +|---|---| +| Editor | What opens projects: your system default, Kate, Neovim (opens in your terminal), VS Code, VSCodium or Zed | +| Terminal | Used for **External** jobs and repository terminals: system default, Ghostty, Konsole, GNOME Terminal, kitty, Alacritty, WezTerm or foot | + +With **system default**, the app uses your `$VISUAL` / `$EDITOR` and `$TERMINAL` settings or your desktop's defaults. + +## 03 Β· Appearance + +Theme (**Dark**, **Light** or **System**), **Text size**, the **Dashboard welcome banner**, **Accent color** (Glacier Β· Cyan, Dusk Β· Violet, Mint Β· Green), **Repository density** (Comfortable or Compact) and **Reduce motion**. + +## 04 Β· Repositories + +| Setting | What it does | +|---|---| +| Repository layout | Cards or List | +| Default sort | Name A–Z, Name Z–A, or Needs attention first | +| Show repository paths | Show or hide full paths | +| Scan depth | How many folder levels below each scan folder to search (1–6) | +| Automatic refresh | Re-read Git status every 30 seconds, 1 minute or 5 minutes, or manually only. This never fetches or pulls | +| Scan folders | One folder per line (`~/…` or absolute). Build and dependency folders such as `node_modules` are skipped | + +## 05 Β· System integrations + +Connects the app to your existing tools. **Detect existing setup** fills empty fields automatically. **Check availability** tests the current values without saving or running anything. + +| Field | What to enter | +|---|---| +| Dotfiles repository | Your dotfiles checkout, containing the Home Manager flake | +| Home Manager profile | The flake output name, for example `commander` | +| Personal backup helper | Your everyday backup script | +| Full backup helper | Your full backup script (runs in a terminal, so it can ask for passwords) | +| Backup health helper | A script that prints backup status as JSON. **It runs automatically for status checks**, so only use a script you trust | +| Restic repository | A local path or a Restic repository address. Don't put a password in the address: addresses that contain one, including `rest:` addresses, are refused. For a REST server, set `RESTIC_REST_USERNAME` and `RESTIC_REST_PASSWORD` in the environment Command Center starts in | +| Restic password file Β· KWallet name / folder / entry | Where to get the repository password. The app stores only *where* the password is, never the password itself | +| Ghostty / Fastfetch source file | The editable files in your dotfiles, not the `/nix/store` copies | +| Encrypted recovery folder | Checked for `.gpg` / `.age` files; they're never opened | +| Recovery instructions | Your "how to rebuild this machine" document | +| Backup freshness (hours) | When a backup counts as overdue | + +## 06 Β· Custom quick actions + +Buttons for your own commands on the dashboard. See [Dashboard β†’ Adding quick actions](Dashboard-and-Needs-Attention#adding-quick-actions). + +## Desktop notifications & tray + +Opt in to notifications for **completed tasks**, **failed tasks** and **health changes**, and set **Quiet hours** (a start and end hour; the same value for both turns quiet hours off). Notifications need `notify-send` and a notification service. This section shows whether they're available. Notifications never include command output. + +## Setup & portability + +- **Setup wizard** reopens the [first-run wizard](Getting-Started#1-the-setup-wizard). +- **Export setup bundle… / Import setup bundle…** move your whole setup between machines. See [Moving to a New Machine](Moving-to-a-New-Machine). + +## Export and import settings + +**Export saved settings** saves just your preferences and custom commands as JSON in Downloads. **Import settings…** previews a file. By default it keeps this machine's paths, apps, integrations and commands, and a checkbox includes them too. The **backup health helper** is never imported. Imported settings land in the draft. Nothing is saved or run until you click **Save settings**. + +For moving everything (workflows, profiles, tools, project settings…), use a setup bundle instead. + +## About & updates + +Shows the installed version. **Check for releases** asks GitHub for the newest release (only when clicked). **Open releases** opens the releases page. **Export source updater** is for installs built from source. See [Installation β†’ Updating](Installation#updating). + +--- + +| | | +|:--|--:| +| [← πŸ•’ Activity & Change Timeline](Activity-and-Change-Timeline) | [🚚 Moving to a New Machine β†’](Moving-to-a-New-Machine) | diff --git a/docs/wiki/System-Sync.md b/docs/wiki/System-Sync.md new file mode 100644 index 0000000..4706b36 --- /dev/null +++ b/docs/wiki/System-Sync.md @@ -0,0 +1,37 @@ +# πŸ”„ System Sync + +> _Dotfiles and Home Manager, one reviewed step at a time._ + +**System Sync** is for people who manage their setup with a **dotfiles repository** and **Home Manager** (Nix). It shows what's changed in your configuration and applies it, one reviewed step at a time. + +Set up the connection first in **Settings β†’ System integrations**: **Dotfiles repository** (the checkout) and **Home Manager profile** (the flake output name, for example `commander`). The flake can sit at the repository root or in `home-manager/`. + +## What you see + +- **Pending source changes:** files changed in your dotfiles checkout, with their diff, plus the branch and how far it is ahead of or behind the remote. +- **Live configuration comparison:** whether your Ghostty and Fastfetch **source** files (in the dotfiles) match the **live** files Home Manager generated, so you can tell what an apply would change. +- **Home Manager generations:** your recent generations, useful for checking what's active or planning a rollback. + +## Updating and applying + +| Button | What it does | +|---|---| +| **Fetch** | Downloads remote changes to your dotfiles without touching your files | +| **Pull updates** | Brings them in (fast-forward only) | +| **Build configuration** | Builds your Home Manager configuration without activating it. A safe way to check for errors | +| **Apply Home Manager** | Builds and switches to the new configuration | + +Each one shows its exact command for review first. + +> [!TIP] +> A typical update is **Fetch β†’ Pull updates β†’ Build configuration β†’ Apply Home Manager**. Save that as a [workflow](Workflows-and-Machine-Profiles) if you do it often. + +## How it fits with Configuration + +The [Configuration](Configuration) page edits your Ghostty and Fastfetch **source** files in the dotfiles. Those edits take effect only after **Apply Home Manager** here. The Configuration page reminds you when a file is managed by Home Manager. + +--- + +| | | +|:--|--:| +| [← πŸ—„οΈ Backup & Restore](Backup-and-Restore) | [πŸŽ›οΈ Configuration β†’](Configuration) | diff --git a/docs/wiki/Toolbox-and-Terminal.md b/docs/wiki/Toolbox-and-Terminal.md new file mode 100644 index 0000000..ce0cf68 --- /dev/null +++ b/docs/wiki/Toolbox-and-Terminal.md @@ -0,0 +1,75 @@ +# 🧰 Toolbox & Terminal + +> _215 Commander Toolbox installers, your own tools, and the built-in terminal._ + +**Toolbox** brings the [Commander Toolbox](https://github.com/Commanderx-code/commander-toolbox) installers into the app: 215 actions across **Applications Setup**, **Gaming**, **Security**, **System Setup** and **Utilities**. They're the same scripts, folders and menus as the terminal version, with a graphical browser on top. + +## Finding a tool + +- Open a category, then its sub-folders. Use the breadcrumbs or **Up** to go back. +- **Search** within the current folder (and everything inside it). Choose **All tools** to search the whole catalog. +- **β˜… Favorites** shows only the tools you've starred. Star a tool with the **β˜…** button on its detail panel. Favorites are saved with your app data and included in [setup bundles](Moving-to-a-New-Machine). +- **Available on this machine** hides tools whose requirements aren't met (wrong distribution, missing interpreter…). Untick it to see everything. +- From a search result, **Open containing folder** jumps to the tool's menu. + +Selecting a tool shows its description, what kind of task it is (installation, file changes, package manager…), whether it's available, and when you last ran it. + +## Quick setup + +Expand **Quick setup** for the most common jobs. Choose **What are you setting up?** (a **Myfish** shell, a **dotfiles** configuration, or an **application**), then **Choose a setup**, and the app opens that tool ready to run. + +## Running a tool + +1. Choose **Run tools in**: the **embedded** terminal (inside the app) or **external** (the terminal app chosen in Settings). +2. Click **Review & run**. The review shows the exact script and folder. +3. Confirm. Installer questions, menus and `sudo` password prompts appear in the terminal exactly as they would in the terminal version, and you answer them there. + +> [!NOTE] +> The app checks compatibility again just before starting. Toolbox scripts keep their own safety checks and confirmations. + +## The Terminal page + +The **Terminal** page is a real terminal session for the running installer or task: + +- Type, answer prompts and use arrow-key menus as usual. It resizes with the window. +- **Stop workflow** cancels the running command. +- **Save output** writes the session to a private file in the app's data folder. Otherwise output is kept only in memory (up to 1 MB) and disappears when you close the app. What you type, including passwords, is never recorded. +- Only one embedded session runs at a time. For image graphics or a second session, use an **external** terminal. + +Return to a session from the **Terminal** page or its entry in **Activity**. + +## Personal tools + +Add your own tools alongside the catalog: scroll to **Personal tools** at the bottom of Toolbox and click **Add personal tool**. + +| Field | Meaning | +|---|---| +| Name, description | How it appears in the list | +| Folder | Where it sits, for example `Maintenance/Backups` (nested folders work) | +| Command | The program and arguments | +| Working folder | Where it runs | +| Required executable | A program that must be installed (checked, not installed for you) | +| Run in | Embedded, External or Background | +| Inputs | Values to ask for each time (text, a folder, or a Git repository folder) | + +**Inputs** let one tool work on whatever you choose. Put a placeholder as a whole argument, for example: + +```text +git -C {repo} status +``` + +Add an input named `repo` of type **Repository folder**. When you run the tool, the app asks you to pick a repository, checks it, and shows the finished command for review. Values are passed exactly as typed, with no shell expansion. For pipes or shell functions, point the tool at a script or use a Fish/Bash [quick action](Dashboard-and-Needs-Attention#adding-quick-actions). + +## Toolbox Updates + +Expand **Toolbox Updates** at the top of Toolbox. Checking never installs anything. + +- **Check catalog updates** compares the bundled Toolbox version with the latest on GitHub and links to the differences. The catalog is built into the app, so taking a newer one means rebuilding it. The panel shows the command for source installs; package users get it with the next release. +- **Check installed-tool updates** lists pending updates by source: Arch packages (using a fresh check where possible, clearly marked if it's the cached list), Flatpak (user and system), and AUR/foreign packages (listed, not checked). +- **Review & update** runs the updater you choose: your Fish `full-upgrade` function, Topgrade, Garuda's updater, a plain Arch update, or Flatpak. It runs in a terminal with the normal prompts. Pick one broad updater or individual ones, not both, so updates don't run twice. + +--- + +| | | +|:--|--:| +| [← πŸ“‚ Repositories](Repositories) | [πŸ” Workflows & Machine Profiles β†’](Workflows-and-Machine-Profiles) | diff --git a/docs/wiki/Troubleshooting-and-FAQ.md b/docs/wiki/Troubleshooting-and-FAQ.md new file mode 100644 index 0000000..7a694e3 --- /dev/null +++ b/docs/wiki/Troubleshooting-and-FAQ.md @@ -0,0 +1,96 @@ +# πŸ›Ÿ Troubleshooting & FAQ + +> _Fixes for common problems._ + +## Installing and starting + +**The .deb or .rpm won't install: "requires libc6 (>= 2.35)" / "GLIBC_2.35".** +Your distribution is older than Command Center supports: it needs glibc 2.35 or newer (Ubuntu 22.04, Debian 12, Fedora 36 or later). Build from source on that machine instead (see [Installation](Installation#building-from-source)). + +**The Arch package complains about library versions.** +The Arch package is built against current Arch. Run `sudo pacman -Syu` first, or build it yourself with `makepkg -si` from `packaging/aur/`. + +**There's no tray icon.** +Tray icons depend on your desktop. GNOME needs an AppIndicator extension, for example. The app works fully without one. + +**Notifications don't appear.** +Install `libnotify` (`notify-send`) and check that notifications are enabled under **Settings β†’ Desktop notifications & tray** and that you're outside **Quiet hours**. + +## Running things + +**"Wait for "…" to finish."** +Another job is using the same folder, the embedded terminal, or (for workstation tasks) the workstation. Wait, or stop it in **Activity**. See [Running several jobs](How-Commands-Run#running-several-jobs). + +**"Settings changed; review the action again."** +Something changed between the review and the start: a setting, a path, a branch. Click the action again to see the updated command. + +**"Action preview expired."** +Reviews last 5 minutes. Click the action again. + +**A job hangs waiting for input.** +Background jobs can't take input. Use an **Embedded** or **External** mode for anything that asks questions or passwords (quick actions, tasks and personal tools let you pick the mode). + +**I can't close the app.** +A job is still running. Wait for it or stop it in **Activity**. + +## Repositories + +**Push/pull fails with an authentication error.** +Git runs without an interactive prompt. Unlock your SSH key (for example with `ssh-add`) or set up a credential helper, or run the command from the repository's terminal. + +**A file shows as changed but `git status` in my terminal says it's clean.** +Previews run with Git filters (such as Git LFS) switched off for safety, so files a filter would normalize can look changed. Check in the terminal. See [Repositories β†’ Good to know](Repositories#good-to-know). + +**"Cannot safely inspect Git configuration" / "Unsupported Git filter configuration".** +The repository's Git settings can't be inspected safely without running something. Use the repository terminal for that one. + +**Ahead/behind numbers look wrong.** +They're from your last fetch. Click **Fetch**. + +**Pull is refused.** +Pull only fast-forwards, on a clean branch. Commit or stash your changes, and resolve diverged branches in the terminal. + +## Backups + +**The backup buttons are disabled.** +Either the helper isn't set in **Settings β†’ System integrations**, or the health helper says your backup drive is disconnected. Plug it in and click **Refresh health**. + +**Backup status says "unknown".** +The health helper didn't report anything. Check its path in Settings and that it prints JSON when run with `--json`. + +**Restic asks for a password or KWallet pops up.** +Actions that open the repository (browse, restore, check, access test) unlock it with the credentials in Settings. KWallet may ask you to unlock the wallet. Status checks never unlock it. + +**Restic jobs say "Use Restic's credential environment or password file instead of a password embedded in the repository URL".** +Your Restic repository address in Settings contains a password, for example `rest:https://user:password@host/`. Command Center refuses these because the address would be passed to restic on the command line, where other users on the machine can read it. Remove the password from the address. For a REST server, set `RESTIC_REST_USERNAME` and `RESTIC_REST_PASSWORD` in the environment Command Center starts in. 0.7.1 and later also refuse `rest:` addresses with a password; earlier versions let them through. + +**File history says the search returned too many matches.** +The pattern matched too many files across all snapshots to display. Search an exact path such as `~/Documents/notes.md`, or a narrower pattern. + +**File history finds nothing, but I know the file was backed up.** +Check the spelling, tick **Ignore case**, or search just the file name. Paths are matched as they were backed up, so an exact-path search must use the full path. + +**My scheduled backup didn't run.** +User timers run while you're logged in, and missed runs happen at your next login. They don't wake a sleeping or powered-off computer. Check **Service logs** for the backup timer. + +## Setup and imports + +**The dashboard says an import was rolled back.** +The app or computer stopped during an import, and your previous setup was restored automatically. Import the bundle again. + +**"Setup changed after preview."** +Your saved setup changed while the import preview was open. Update the preview and review again. + +**My Toolbox favorites disappeared after upgrading.** +From 0.6.0 they're saved with your app data. They're moved over automatically the first time you open Toolbox in the desktop app. If they're gone, star them again, and they'll stay from then on. + +## Still stuck? + +> [!TIP] +> Check the job's output in **Activity**, then [open an issue](https://github.com/Commanderx-code/command-center/issues) with your version (**Settings β†’ About & updates**), distribution, and the steps to reproduce. Remove anything private from logs first. + +--- + +| | | +|:--|--:| +| [← πŸ”’ Your Data & Privacy](Your-Data-and-Privacy) | [🏠 Home β†’](Home) | diff --git a/docs/wiki/Workflows-and-Machine-Profiles.md b/docs/wiki/Workflows-and-Machine-Profiles.md new file mode 100644 index 0000000..d38f63b --- /dev/null +++ b/docs/wiki/Workflows-and-Machine-Profiles.md @@ -0,0 +1,64 @@ +# πŸ” Workflows & Machine Profiles + +> _Repeatable maintenance routines and new-machine recipes._ + +The **Workflows** page saves routines you repeat, so you don't have to remember the order: + +- **Maintenance workflows**, such as "check the backup drive β†’ back up β†’ check the repository β†’ check services and disks". +- **Machine profiles**, which are setup recipes for a workstation, laptop or fresh install. + +> [!IMPORTANT] +> Both are built from the same kinds of steps, and **every step is still reviewed before it runs**. + +## Step types + +| Step | What it does | +|---|---| +| Check backup drive | Confirms the backup health helper reports the drive connected | +| Run personal backup | Runs your personal backup helper | +| Check Restic repository | Checks the Restic repository's integrity | +| Build Home Manager / Apply Home Manager | Builds, then switches to, your Home Manager configuration | +| Fetch dotfiles / Pull dotfiles | Updates your dotfiles checkout | +| Fetch repository | Fetches a chosen repository | +| Clone repository | Clones a repository into a new folder (useful in machine profiles) | +| Run Toolbox installer | Runs a Toolbox tool | +| Run saved quick action | Runs one of your [quick actions](Dashboard-and-Needs-Attention#adding-quick-actions) | +| Run personal tool | Runs one of your [personal tools](Toolbox-and-Terminal#personal-tools) | +| Update packages | Runs a system updater | +| Check services and disk usage | Reports disk usage and failed services | + +## Creating a workflow + +1. Click **New workflow** (or **Add weekly maintenance example** for a ready-made starting point). +2. Name it, then **Add step** for each step. Reorder with the up buttons, remove what you don't need. +3. **Save recipe**. + +The weekly maintenance example is: Check backup drive β†’ Run personal backup β†’ Check Restic repository β†’ Check services and disk usage. Add an **Update packages** step if you want updates in the same routine. + +## Running a workflow + +1. Click **Start workflow**. A progress panel lists every step. +2. Click **Review next step**, check the command, and confirm. +3. When a step succeeds, the next one becomes available. Nothing moves on by itself. + +A failure, cancellation or timeout **stops the sequence**. Look at the step's output in Activity, then use **Review retry of current step** to try again. A failed command may have partly run, so check first. **Stop sequence** prevents further steps; to stop the step that's running now, use Activity or its terminal. + +Interactive steps open in the terminal so you can answer prompts. Workflow steps are workstation tasks, so only one runs at a time. Repository jobs in other folders can still run alongside (see [How Commands Run](How-Commands-Run#running-several-jobs)). If the app closes mid-workflow, the sequence shows as **interrupted** and waits for you to review it. + +## Machine profiles + +A machine profile describes how to set up a machine: which repositories to clone, which Toolbox installers to run, and which configuration to apply. + +1. Click **New machine profile** and add steps, as with a workflow. +2. Optionally set **Dotfiles checkout for this machine** and **Home Manager profile**. Leave them blank to use the ones in Settings. +3. For steps that might already be done, fill in **Optional presence check** with a path. If that file or folder exists, the step is marked **Present Β· inspect before skipping**. + +**Review profile** shows, for the current machine, which steps are ready to run and which need setup first. You can **Skip inspected step** (with confirmation) for things already in place. The app never skips anything by itself, because a file being present doesn't prove it's the right version. + +Profiles run on **this** computer only. Clone targets must be new folders; nothing is overwritten. Toolbox installers still ask their own questions. The setup wizard can inspect a profile, and [setup bundles](Moving-to-a-New-Machine) carry your profiles to the new machine. + +--- + +| | | +|:--|--:| +| [← 🧰 Toolbox & Terminal](Toolbox-and-Terminal) | [πŸ—„οΈ Backup & Restore β†’](Backup-and-Restore) | diff --git a/docs/wiki/Your-Data-and-Privacy.md b/docs/wiki/Your-Data-and-Privacy.md new file mode 100644 index 0000000..0328376 --- /dev/null +++ b/docs/wiki/Your-Data-and-Privacy.md @@ -0,0 +1,46 @@ +# πŸ”’ Your Data & Privacy + +> _What's stored, where, and what never leaves your machine._ + +Command Center is local-only. There's no account, no cloud service and no telemetry. It contacts the internet only when you do something that needs it: Git fetch, pull and push, Toolbox installers downloading their packages, update checks you click, or Restic reaching a remote repository. + +## What's stored, and where + +| What | Where | +|---|---| +| Preferences (plus the previous version as `.bak`) | `~/.config/io.helixstack.commandcenter/settings.json` | +| Project groups, launch profiles, tasks | `~/.local/share/io.helixstack.commandcenter/workspace.json` | +| Workflows, machine profiles, personal tools, notifications | `~/.local/share/io.helixstack.commandcenter/operations.json` | +| Toolbox favorites | `~/.local/share/io.helixstack.commandcenter/toolbox-favorites.json` | +| Activity (last 100 jobs, including their output) | `~/.local/share/io.helixstack.commandcenter/activity.json` | +| Configuration backups | `~/.local/share/io.helixstack.commandcenter/config-backups/` | +| Pre-import backups | `~/.local/share/io.helixstack.commandcenter/setup-backups/` | +| Terminal output you chose to save | `~/.local/share/io.helixstack.commandcenter/toolbox-output-