Metadata-Version: 2.4
Name: SyncPrjs
Version: 1.5.0
Summary: A robust command-line tool for managing multiple projects that follow a prefix-suffix naming convention.
Author-email: Wilgat Wong <wilgat.wong@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Wilgat/SyncPrjs
Project-URL: Repository, https://github.com/Wilgat/SyncPrjs
Project-URL: Issues, https://github.com/Wilgat/SyncPrjs/issues
Keywords: logging,sudo,chronicle,example
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: ChronicleLogger>=1.3.1
Dynamic: license-file

# SyncPrjs - Universal Multi-Prefix Project Manager

[![Version](https://img.shields.io/badge/Version-1.5.0-blue?style=flat-square)](https://github.com/Wilgat/SyncPrjs)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![CIAO](https://img.shields.io/badge/Philosophy-CIAO%20(Caution%20%E2%80%A2%20Intentional%20%E2%80%A2%20Anti--fragile%20%E2%80%A2%20Over--engineered)-purple.svg)](https://github.com/cloudgen/ciao)
[![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=flat-square)]()

**Official Recommendation from [grok](https://grok.com/share/c2hhcmQtNA_0726ccc0-a784-4ad2-a1e5-d16de705977e)** — see [local copy](RECOMMENDATION.md)

**A robust, CIAO-defensive command-line tool for managing hundreds of prefix-suffix AI desktop clients.**

This project follows strict **[CIAO defensive programming principles](https://github.com/cloudgen/ciao)**.

---

## Overview

SyncPrjs manages large collections of projects following the `prefix-suffix` naming convention (e.g. `grok-iron`, `gm-1n4003`, `poe-trade`, `cf-iron`).

It is specifically designed for GNOME C/GTK applications using `WebKitWebView`, with persistent cookie/session management for Google and Cloudflare services.

### Key Capabilities

- Smart Google cookie synchronization (**user chooses any source prefix**, gm-* recommended)
- Safe Cloudflare-only cookie synchronization (v3)
- Project code templating with automatic suffix renaming
- Automatic backups before any cookie modification
- **Auto-start with configurable launch interval + per-project SHUTDOWN timer**
- Suspend / Un-suspend projects by suffix
- Full `--quiet` and `--json` support for scripting

**Powered by [ChronicleLogger 1.3.0+](https://pypi.org/project/ChronicleLogger/)**

---

## Installation

```bash
pip install SyncPrjs
```

Or from source:

```bash
git clone https://github.com/Wilgat/SyncPrjs.git
cd SyncPrjs
pip install -e .
```

The command `sync-prjs` will be available in your PATH.

---

## Usage

### 1. Interactive Mode (Default)

```bash
sync-prjs
```

Main menu (updated for 1.5.0):

```
0. Auto-start projects by prefix (configurable delay + SHUTDOWN)
1. Sync Google cookies (Smart merge)
2. Sync Google cookies (Missing folders only)
3. Sync project code
4. Sync Cloudflare cookies by prefix (v3 - safe)
5. Inspect cookies (Google + Cloudflare + Others)
6. Restore cookies from backup
7. Remove backup folders (sync + cookie backups)
8. Clean all backup folders (old behavior)
9. Show cookie database structure (debug schema)
10. Suspend projects by suffix (add .suspended)
11. Un-suspend projects by suffix (remove .suspended)
Q. Quit
```

**New in 1.5.0 (Options 1 & 2):**  
When you select **1** (Smart merge) or **2** (Missing folders only), you will now be prompted to **choose the SOURCE prefix** (gm- is shown as recommended).  
The tool will automatically exclude projects with the chosen source prefix from targets and, if the source is **not** gm-, it will also include gm-* projects as targets — exactly as you requested.

### 2. Non-Interactive & Automation Mode

#### Auto-start with Configurable Interval + SHUTDOWN (New in 1.4.4)

```bash
# Auto-start all gm-* projects with 8 seconds interval between launches
sync-prjs autostart --prefix gm --interval 8

# Auto-start with custom interval and auto-shutdown timer
sync-prjs autostart --prefix gm --interval 15 --shutdown 300

# Quiet + JSON for automation
sync-prjs autostart --prefix cf --interval 10 --shutdown 600 --quiet --json
```

**CLI Flags (recommended):**
- `--interval`, `--delay <seconds>` : Delay in seconds between launching each project (default: 20)
- `--shutdown <seconds>` : Auto-shutdown each launched project after N seconds (0 = never, default: 0)
- `--prefix <prefix>` : Required for autostart (e.g. `gm`, `cf`, `poe`)

You can also combine with environment variables as fallback:

```bash
SHUTDOWN=180 INTERVAL=12 sync-prjs autostart --prefix gm
```

#### Other Commands

```bash
sync-prjs about                    # Version + diagnostics
sync-prjs help                     # Show complete help
sync-prjs inspect --project gm-1n4003
sync-prjs cf-sync --source cf-iron
sync-prjs code-sync --source grok-iron
```

---

### Full Command Reference

| Command                        | Description                                      | Key Options                                      |
|-------------------------------|--------------------------------------------------|--------------------------------------------------|
| `sync-prjs`                   | Interactive menu                                 | -                                                |
| `sync-prjs autostart`         | Auto-start projects by prefix                    | `--prefix gm`, `--interval 10`, `--delay 10`, `--shutdown 300` |
| `sync-prjs inspect`           | Cookie statistics                                | `--project <name>`, `--json`                     |
| `sync-prjs google-sync`       | Smart Google cookie merge                        | - (interactive source prefix selection)          |
| `sync-prjs cf-sync`           | Cloudflare-only sync (v3)                        | `--source <project>`                             |
| `sync-prjs code-sync`         | Code + suffix sync                               | `--source <project>`                             |
| `sync-prjs about`             | Version & diagnostics                            | `--quiet`, `--json`                              |
| `sync-prjs help`              | Show complete help                               | `--quiet`, `--json`                              |

**Global Options:**
- `--quiet`, `-q` — Suppress all non-essential output
- `--json` — Machine-readable JSON output (implies --quiet)

---

### Environment Variables

- `SHUTDOWN=N` — Auto-shutdown each launched project after N seconds (0 = never)
- `INTERVAL=N` — Launch interval in seconds (CLI flag takes precedence)
- `JSON=1` — Force JSON output mode
- `QUIET=1` — Quiet mode

---

## New in 1.5.0 (2026-05-20)

- **Sync Google cookies (Options 1 & 2)** now lets you **choose any source prefix** interactively (gm- recommended).  
  The chosen prefix is excluded from targets. If the source is **not** gm-, then gm-* projects are automatically included as targets.
- Fixed interactive selection helper (`choose_one`) for full compatibility.
- All previous safety, backups, quiet/JSON mode, and CIAO defensive style preserved.

---

## Project Naming Convention

All projects must follow: `<prefix>-<suffix>`

**Common prefixes:** `gm-`, `grok-`, `poe-`, `cf-`, `yt-`, etc.

---

## Cookie Storage Location

```
~/.app/<full-project-name>/cookies/cookies.sqlite
```

---

## Important Notes

- Always run `sync-prjs` from the directory containing your prefix-suffix project folders.
- Cookie backups are created automatically before any modification.
- Full CIAO defensive style maintained.

---

## Development Philosophy

This tool is built with **CIAO Defensive Programming Principles** to survive repeated AI-assisted modifications.

**Requires ChronicleLogger 1.3.0+**

---

## Links

- [ChronicleLogger on PyPI](https://pypi.org/project/ChronicleLogger/)
- [CIAO Philosophy](https://github.com/cloudgen/ciao)

---

**Made with ❤️ for power users managing large collections of AI desktop clients.**

**Last updated:** May 20, 2026
