Merge hardening update and prepare 1.0.1

Author: Evan1108-Coder

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Report a reproducible problem
+title: "[Bug]: "
+labels: bug
+---
+
+## What happened?
+
+## Steps to reproduce
+1.
+2.
+3.
+
+## Expected behavior
+
+## Environment
+- OS:
+- Version/commit:
+
+## Logs or screenshots
+Remove secrets before pasting logs.

.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## Summary
+
+## Validation
+- [ ] Tests/checks run
+- [ ] Documentation updated
+- [ ] No secrets committed
+
+## Screenshots / notes

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+# Cancel superseded runs on the same ref to save CI minutes.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    name: Build & test (Node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The dev/test toolchain (vitest 4 via rolldown) requires Node 20+
+        # (it imports `styleText` from node:util, added in Node 20). The published
+        # CLI bundle still targets Node 18, but CI builds and tests on 20/22.
+        node: ["20", "22"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+      # The test suite is fully offline (no live AI provider calls), so no API keys are needed.
+      - name: Test
+        run: npm test

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to Setupr will be documented in this file. Setupr keeps a changelog because it is a versioned developer tool with user-facing CLI behavior.
+
+## Unreleased
+
+### Added
+- Added real repository visual snapshot assets generated from the current file tree.
+- Added public maintenance documentation updates: security policy, issue/PR templates, and repository snapshot notes.
+
+### Validation
+- Re-ran the documented test suite during the polish pass and recorded the real test status in `docs/project-snapshot.md`.
+
+## Initial Public Version
+
+- Published the first public project version.

README.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are handled on the default branch unless a release branch is explicitly listed.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for a suspected vulnerability. Email the maintainer or use GitHub's private vulnerability reporting when available. Include:
+
+- Affected version or commit
+- Steps to reproduce
+- Impact and likelihood
+- Any relevant logs with secrets removed
+
+## Secret Handling
+
+Never commit API keys, Telegram tokens, OAuth credentials, database files, `.env` files, or local user exports. Use `.env.example` for placeholders only.
+
+Secrets are redacted on a best-effort basis (`redactText`/`redactObject` in `src/core/engine.ts`) before commands, history, and logs are persisted. This targets common token shapes and `NAME=value` credential assignments — it is not a guarantee that no secret will ever reach a log file.
+
+## Threat Model
+
+Setupr runs real shell commands on your machine with your full user privileges. The command-safety
+layer (`src/agent/safety.ts`) is a **best-effort, defense-in-depth guard, not a sandbox.** It
+classifies each planned command and decides whether to allow, confirm, or block it:
+
+- **Block (cannot be bypassed by `--force`)** — clearly destructive or hostile patterns such as
+  `rm -rf /` (and `~`, `*`, `$HOME` variants), `sudo`, `chmod 777`, `chown -R`, and
+  `curl … | sh`/`| bash` pipe-to-shell installs.
+- **Confirm** — high/medium-risk commands (dependency installs, commands that delete files or reset
+  git state, commands that embed a secret value or `KEY=value` credential assignment). `--force`
+  may proceed past a **medium**-risk confirmation using safe defaults, but **never** past a
+  high-risk or blocked one.
+- **Allow** — everything else.
+
+What this layer is **not**:
+
+- **Not a security boundary.** Anything you could run in your shell, a command run through Setupr
+  can run.
+- **The block list is a denylist, and denylists are inherently incomplete.** It catches common,
+  obvious footguns; an obfuscated or equivalent destructive command can get past it. Treat the
+  guard as a seatbelt, not a vault door.
+- **Trust the project and its AI-generated plan.** When AI planning is enabled, setup steps may be
+  proposed by a model based on the project's contents. Review the plan — especially before using
+  `--force` — the way you would review a shell script you downloaded.
+
+Recommendations: run Setupr only against projects you trust, read the pre-execution plan before
+confirming, be deliberate with `--force`, and keep real secrets in `.env` files rather than inline
+in commands.

SECURITY.md

@@ -0,0 +1,105 @@
+# Commands
+
+Full reference of all Setupr CLI commands.
+
+## TUI Commands (Rich Interactive UI)
+
+| Command | Description |
+|---------|-------------|
+| `setupr` / `dashboard` | Project dashboard with health, git, env, processes, history, and quick commands |
+| `setup` | Full project setup — scan, install runtime, deps, env, verify |
+| `chat <question>` | AI director chat TUI for project questions, steering, plans, logs, and context |
+| `status` | Dashboard/status view with plain, JSON, or TUI output |
+| `start` | Start and track a managed project process |
+| `doctor` | Diagnose environment health (runtimes, deps, ports) |
+| `update` | Check for dependency updates with breaking change warnings |
+| `clean` | Review and remove artifacts (`--deps`, `--share`, `--all`; positional `deps`, `share`, `all` also work) |
+| `env` | Open the .env editor TUI or manage project .env files from .env.example |
+| `auth` | Manage global Setupr AI provider API keys and models |
+
+## Non-TUI Commands (Plain Terminal)
+
+| Command | Description |
+|---------|-------------|
+| `env init\|check\|sync\|smart` | Manage .env files in plain mode with subcommands |
+| `ps` | List Setupr-managed processes |
+| `stop [target]` | Stop one or all managed processes |
+| `restart [target]` | Restart a managed process |
+| `info` | Show project summary |
+| `list` | List available scripts/commands |
+| `run <script>` | Run a project script |
+| `switch <version>` | Switch runtime version |
+| `add <package>` | Smart add dependency |
+| `remove <package>` | Remove dependency |
+| `port [number]` | Check/find/kill port |
+| `deps [list\|audit\|why\|licenses]` | Dependency tree, audit summary, package reasoning, and license checks |
+| `config` | Manage setupr config |
+| `help [command]` | Show global or command-specific help |
+| `lock` | Snapshot environment state |
+| `diff` | Compare current vs locked state |
+| `logs [target]` | Show managed process logs, falling back to package-manager logs |
+| `test [run\|quick\|full\|ci\|smoke\|unit\|integration\|e2e\|watch\|coverage\|changed\|file\|failed\|doctor\|list\|report\|clean\|fix\|security]` | Run verification suites, smoke checks, and reports |
+| `security [scan\|quick\|deep\|deps\|secrets\|env\|docker\|ci\|code\|routes\|auth\|headers\|doctor\|report\|baseline\|ignore\|fix\|watch\|test]` | Run defensive security scans, baselines, ignores, and safe fixes |
+| `fix [doctor\|env\|lint\|format\|security\|all]` | Preview or run grouped safe fixes |
+| `release [check\|publish-check\|notes\|version]` | Release readiness checks, package dry-runs, notes, and version summaries |
+| `perf [startup\|scan\|context\|status]` | Measure Setupr scan/context/status performance |
+| `github [status\|ci\|pr\|issue]` | Show GitHub repository, Actions, PR, and issue targets |
+| `registry <npm\|pypi\|crates> <package>` | Look up package registry information |
+| `build` | Detect and run build command |
+| `deploy` | Run deploy scripts |
+| `open [repo\|ide]` | Open in browser/IDE/repo |
+| `git` | Git workflows plus commit-message, PR-description, branch-check, and conflict helper |
+| `init` | Scaffold new projects from stacks or templates |
+| `migrate <npm\|yarn\|pnpm\|bun>` | Migrate package manager metadata and lockfiles |
+| `ci <github\|gitlab\|bitbucket\|circleci>` | Generate CI/CD config |
+| `docker <generate\|compose\|check>` | Generate Dockerfile/compose files or check Docker readiness |
+| `secrets <init\|set\|get\|list\|remove\|export\|import\|rotate>` | Manage encrypted project-local secrets |
+| `templates <new\|list\|save\|remove>` | Create, save, list, or remove templates |
+| `workspace <list\|run\|exec\|add\|info\|check>` | Operate on monorepo workspaces |
+| `health [full\|deps\|security\|outdated\|size]` | Run project health checks |
+| `share <export\|import\|inspect>` | Export/import shareable setup bundles |
+| `notes <add\|list\|remove\|clear>` | Manage project-local notes in `.setupr` |
+| `history [list] [limit]` | Show recent project-local Setupr history |
+| `context <show\|export\|import>` | Export/import notes and history for team handoff |
+| `plugin <create\|validate\|doctor\|install\|remove\|list\|info\|enable\|disable>` | Manage Setupr plugins and plugin development |
+| `lint <run\|setup\|fix>` | Run or set up linting |
+| `format <run\|check\|setup>` | Run or set up formatting |
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Skip safe prompts, install what project specifies, and stop only for blockers or destructive choices |
+| `--no-tui` / `--plain` | Plain terminal output for CI/CD, piping, SSH |
+| `--deps` | With `clean`, remove dependency/cache artifacts |
+| `--share` | With `clean`, remove sensitive/local-only files before sharing a project |
+| `--all` | With `clean`, remove dependencies, build output, caches, and local env files |
+
+## TUI Navigation
+
+- **Arrow keys**: Move between neighboring panels in the dashboard
+- **Tab / Shift+Tab**: Move to the next or previous focusable panel
+- **Mouse click**: Focus a panel in terminals that support SGR mouse events
+- **Mouse click inside focused input**: Move the text cursor where the terminal reports coordinates accurately
+- **Option/Alt+Arrow**: Move by word where the terminal sends a compatible sequence
+- **Option/Alt+Delete or Ctrl+W**: Delete the previous word
+- **Ctrl+A / Ctrl+E**: Jump to start/end of input
+- **Ctrl+U / Ctrl+K**: Clear before/after cursor
+- **Enter**: Confirm / submit focused inputs
+- **Esc**: Leave or skip the active input when supported
+- **q**: Quit when focus is not inside an input
+
+The TUI runs in the terminal alternate screen, so exiting returns to the original shell history instead of leaving the dashboard printed in the scrollback. It enables SGR mouse reporting and bracketed paste while active, then disables both on cleanup. It does not set a background color; Terminal, iTerm2, Ghostty, and other terminal profiles keep control of their own theme/background. Panels are drawn with Unicode box-drawing characters because terminal UIs render in character cells rather than graphical window primitives.
+
+Setupr TUIs share the same terminal-native style: blue uppercase panel titles, thin blue borders, yellow focused borders/actions, green success states, yellow warnings/current work, and red failures. Interactive inputs stay anchored at the bottom of their panel, wrap within the box, and scroll once long input reaches the panel's line cap. `setupr clean` opens a safety review first; type `CLEAN` to delete reviewed targets, or use `--force` only when you intentionally want Setupr to skip the review prompt.
+
+## Help
+
+```bash
+setup help
+setup help auth
+setup auth --help
+setup help auth set-key
+```
+
+Global help lists every command. Command help shows subcommands, variations, options, and examples for that command.

docs/COMMANDS.md

@@ -0,0 +1,137 @@
+# Setupr Features
+
+## Smart Detection
+
+Setupr automatically detects:
+- **Languages**: TypeScript, JavaScript, Python, Rust, Go, Java, Ruby, PHP, Dart, Elixir, Swift, C#, Kotlin, Scala, and more
+- **Frameworks**: Next.js, Nuxt, SvelteKit, React, Vue, Angular, Express, Django, Flask, Rails, Spring Boot, and 20+ more
+- **Package Managers**: npm, yarn, pnpm, bun, pip, poetry, cargo, go, bundler, composer, pub, mix
+- **Services**: PostgreSQL, MySQL, MongoDB, Redis, RabbitMQ, Elasticsearch, Docker
+- **Monorepos**: npm workspaces, pnpm workspaces, Turborepo, Lerna, Nx
+
+### Detection Priority
+
+1. `.setupr.json` config file (explicit, highest priority)
+2. `package.json` "setupr" field
+3. File-based scanning (lock files, config files)
+4. Content analysis (dependency inspection)
+5. AI fallback (novel situations only)
+
+## AI-Powered Intelligence
+
+Setupr uses a 3-tier progressive intelligence system:
+
+1. **Pattern Matching** (Level 0) — Free, instant. Handles ~80% of queries
+2. **Cached Responses** (Level 1) — Free after first hit. Smart deduplication
+3. **Live AI** (Level 2) — Only for novel situations. Uses compressed DSL for minimal token usage
+
+The compressed DSL is internal-only. Setupr compresses docs, scan facts, and parsed user intent before sending context to a model, but generated explanations, docs, code edits, commands, and TUI messages stay in normal human-readable language.
+
+Supports 7 AI providers (25+ models, plus custom GitHub Models catalog IDs):
+
+| Provider | Models | Env Key |
+|----------|--------|---------|
+| OpenAI | gpt-5.4-pro, gpt-5.4-mini, gpt-4o, gpt-4o-mini | `OPENAI_API_KEY` |
+| Anthropic | claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5, claude-3.5-sonnet | `ANTHROPIC_API_KEY` |
+| Google | gemini-3.1-pro, gemini-3-flash, gemini-2.5-flash-lite | `GOOGLE_API_KEY` |
+| Groq (Llama) | llama-4-maverick, llama-4-scout, llama-3.3-70b | `GROQ_API_KEY` |
+| MiniMax | minimax-m2.7, minimax-m2.5-lightning | `MINIMAX_API_KEY` |
+| Moonshot (Kimi) | kimi-latest, kimi-k2-thinking, kimi-k2-turbo-preview, kimi-k2.5-vision, moonshot-v1-128k | `MOONSHOT_API_KEY` |
+| GitHub Models | openai/gpt-4.1, openai/gpt-4.1-mini, openai/gpt-4o, openai/gpt-4o-mini, or any GitHub catalog ID | `GITHUB_MODELS_API_KEY`, `GITHUB_TOKEN`, or `GITHUB_API_KEY` |
+
+```bash
+# Guided setup for provider API keys
+setup auth login
+
+# Save one provider API key globally
+setup auth set-key github
+
+# View configured providers without printing raw keys
+setup auth list
+
+# Test configured providers with tiny requests
+setup auth test
+
+# View available models
+setup auth models
+
+# Set preferred model
+setup auth use openai/gpt-4.1-mini
+```
+
+Setupr stores provider API keys globally in `~/.setupr/secrets.json` with file permissions `0600`. Raw keys are never printed.
+
+### AI Director Runtime
+
+Setupr's AI layer is a director runtime, not a one-shot planner:
+
+- Reads bounded project context from README/setup docs, `.env.example`, package scripts, Docker files, CI files, and scanner output
+- Compresses setup docs into compact facts before model calls
+- Parses user chat into compact intent facts while preserving the exact raw message for AI fallback
+- Caches context under `.setupr/cache` so startup stays fast
+- Turns failures into structured diagnosis and safe re-planning decisions
+- Shows plan diffs when chat steering changes the active plan
+- Writes agent workflow checkpoints to `.setupr/agent-workflow.json` so interrupted flows can resume
+
+AI output is not treated as unrestricted shell text. The director proposes structured actions, then Setupr's executor and safety policy decide whether the action is allowed, needs confirmation, or must be blocked.
+
+```bash
+setupr chat
+setupr chat "how do I start this app?"
+setupr chat "what failed last time?"
+setupr chat "switch model to moonshot-v1-128k"
+setupr chat --new
+setupr chat resume
+```
+
+## Agent-Guided TUI Flow
+
+The `setup` TUI is an agent workspace, not just a log viewer:
+
+- Before the dashboard opens, Setupr prints a plain-text warning describing what it may do
+- Inside the TUI, the main panel shows a time-ordered timeline: system events, AI decisions, user messages, command output, warnings, and confirmations
+- When the agent needs input, it pauses with an option card above the persistent chat input
+- The AI director can act on natural language while setup is open: change models, fill env values, skip or rewrite plan steps
+- `--force` skips safe prompts and uses defaults where possible, but does not invent secrets and still stops for blockers
+
+## Safety Policy
+
+All command-like actions pass through one safety layer. Safe checks and normal dependency installs can run. Medium/high-risk actions require confirmation. Critical actions (root/home wildcard deletion, `curl | sh`, unsafe elevated commands) are blocked. `--force` never bypasses critical safety blockers.
+
+## Environment Management
+
+```bash
+setup env            # Open interactive .env editor TUI
+setup env init       # Create .env from .env.example
+setup env check      # Check for missing variables
+setup env sync       # Sync structure with .env.example
+setup env smart      # Smart reorganize + auto-fill
+```
+
+## Checkpoint & Resume
+
+- Progress saved to `.setupr/checkpoint.json`
+- Agent workflow state saved to `.setupr/agent-workflow.json`
+- Setup stops on the first failed step (non-zero exit in plain mode)
+- Persists across terminals and reboots
+- Automatically cleaned up on success
+
+## Verification And Security
+
+```bash
+setupr test quick                          # Fast local check
+setupr test full --report .setupr/test-report.md  # Broader check
+setupr test doctor                         # Coverage explanation
+setupr security scan                       # Defensive local scan
+setupr security deep --report .setupr/security-report.json
+```
+
+## Plugin Development
+
+```bash
+setupr plugin create team-tools
+setupr plugin validate .
+setupr plugin doctor
+```
+
+Plugins extend Setupr with commands, scanners, planners, doctor checks, fixers, and TUI panels. Plugin-proposed work still routes through Setupr's safety systems.