InstantRepo

InstantRepo be local setup helper. Give it Git repo URL or folder. It clone or read repo, detect stack, check local tools, find env needs, scan for risky files, then make setup plan.

It have three faces:

• Wails desktop app for Windows.
• Go CLI mirror for repo, env, vault, settings, diagnostics, and shell metadata.
• HTTP API for tool use.

Caution

InstantRepo can run commands from repos. Treat unknown repos as unsafe. Read plan and safety notes before approve run.

What It Does

• Clone GitHub, GitLab, or other Git URL into chosen folder.
• Analyze local repo folder.
• Detect Node.js, Python, and Go projects.
• Detect local tools like git, node, bun, npm, pnpm, python, go, and docker.
• Read README.md for install, run, env, and service hints.
• Detect .env templates and needed secret values.
• Draft or update grouped local .env targets with safe defaults, while keeping existing values.
• Store approved service credentials through the operating system credential store for reuse in Env Drafts.
• Detect Docker Compose services like Postgres, MongoDB, Redis, and MySQL.
• Flag scripts, installers, and binaries before run.
• Classify setup steps as required, recommended, optional, manual, or uncertain.
• Execute one approved step at a time.

Env Draft Direction

.env setup is core product work. Current app can draft or update grouped local env files with safe defaults, topology-aware local URLs and ports, generated local secrets, and vault-backed service credential references while keeping existing values.

Current Env Draft foundation includes:

• App Topology first: detect frontend, backend, workers, databases, caches, and providers before guessing URLs or ports.
• Env Default Catalog: classify dev defaults, generated local secrets, service credentials, and provider config through app-shipped rules.
• Multi-target Save All: handle root, client, server, and weird local .env* files in one view.
• User Env Vault backend: store approved service credentials in the OS credential store and keep only metadata, approvals, fingerprints, and use records in the Local App Database.
• Deepened Env Draft internals: target inference and save policy now live behind smaller behavior-tested modules.

The Env Draft foundation roadmap is complete through Env Vault Manager, Env Pattern Contribution, and AI Env Review Bundle support.

See CONTEXT.md and docs/adr/0002-use-catalog-driven-env-drafts.md for the product rules.

CLI Mirror

Current code mirrors Wails app operations through production-safe CLI subcommands where command-line use makes sense. CLI is product surface for users, devs, and agents, not a QA-only backdoor.

The CLI mirror track covers:

• foundation subcommands with human output by default and --json for agents
• structured JSON errors and CLI contract version metadata
• app-data isolation through --app-data-dir or INSTANTREPO_APP_DATA_DIR
• repository analyze, clone preflight, import, and execute flows
• Env Draft generate/save flows
• installed repo history and credential-free diagnostics
• Env Vault, contribution settings, AI Env Review settings, and bridge contract metadata

Foundation work in #35, repository mirror work in #36, Env Draft mirror work in #37, installed repo history/diagnostics in #38, Env Vault CLI work in #39, and settings/bridge metadata in #40 are implemented in this codebase.

See #34, child issue #41, and docs/cli-mirror.md for CLI command map, JSON envelope, structured errors, app-data isolation, OpenDirectory() scope, and private QA boundary. Issue tracker closure may lag local docs/code; verify GitHub state before calling roadmap closed. See docs/adr/0003-use-private-local-qa-harness-with-safe-cli-surfaces.md for why private QA stays local.

Project Shape

cmd/instantrepo             Go CLI and API entrypoint
cmd/instantrepo-wails       Wails desktop app backend
cmd/instantrepo-wails/frontend
                            React + Vite UI, built with Bun
internal/command            CLI mirror parser, app-data policy, JSON envelopes
internal/analyzer           Repo, README, runtime, env, and service detection
internal/service            Planning, execution, env writing, Env Vault, repo clone flow
internal/api                HTTP endpoints
internal/domain             Shared response and plan types
internal/store              SQLite local metadata, setup sessions, Env Vault metadata
test                        Manual MVP test plan and repo matrix

Prereqs

• Go 1.26.2
• Bun 1.3.3 or newer
• Wails CLI for desktop dev and build
• Git

Install frontend deps:

cd cmd/instantrepo-wails/frontend
bun install

Desktop App

Run dev app:

cd cmd/instantrepo-wails
wails dev

Build Windows app:

cd cmd/instantrepo-wails
wails build -clean

Output app:

cmd/instantrepo-wails/build/bin/InstantRepo.exe

CLI

CLI mirror subcommands print human text by default. Add --json for stable success/error envelopes and contract metadata. Legacy root flags are compatibility entrypoints and may emit older payloads. See docs/cli-mirror.md for the full mirror contract.

Show CLI version and contract metadata:

go run ./cmd/instantrepo version --json

Analyze repo URL:

go run ./cmd/instantrepo repo analyze --repo https://github.com/user/repo

Analyze local path:

go run ./cmd/instantrepo repo analyze --path C:\path\to\repo

Check clone target before import:

go run ./cmd/instantrepo repo preflight --repo https://github.com/user/repo --destination C:\work

Import or clone repo:

go run ./cmd/instantrepo repo import --repo https://github.com/user/repo --destination C:\work
go run ./cmd/instantrepo repo clone --repo https://github.com/user/repo --destination C:\work

Run one plan step:

go run ./cmd/instantrepo repo execute --path C:\path\to\repo --step install-node-deps --approve

List installed repos and setup history:

go run ./cmd/instantrepo repo list --json
go run ./cmd/instantrepo repo details --id 123 --json

Export credential-free repo diagnostics:

go run ./cmd/instantrepo repo diagnostics --path C:\path\to\repo --json
go run ./cmd/instantrepo repo diagnostics --id 123 --json

Generate structured Env Draft JSON:

go run ./cmd/instantrepo env draft generate --path C:\path\to\repo --json

Save a structured Env Draft from a file:

go run ./cmd/instantrepo env draft save --path C:\path\to\repo --file C:\path\to\draft.json --json

Save a raw .env for repos with one inferred env target:

go run ./cmd/instantrepo env raw save --path C:\path\to\repo --file C:\path\to\.env --json

Manage Env Vault metadata and approvals:

go run ./cmd/instantrepo env vault list --json
go run ./cmd/instantrepo env vault save --provider openai --variable OPENAI_API_KEY --display-name "OpenAI dev key" --stdin --json
go run ./cmd/instantrepo env vault update --id 123 --display-name "OpenAI work key" --json
go run ./cmd/instantrepo env vault update --id 123 --stdin --json
go run ./cmd/instantrepo env vault remove --id 123 --json
go run ./cmd/instantrepo env vault approve --id 123 --repo-path C:\path\to\repo --target .env --variable OPENAI_API_KEY --json
go run ./cmd/instantrepo env vault revoke --approval-id 456 --json
go run ./cmd/instantrepo env vault status --id 123 --status action_needed --json
go run ./cmd/instantrepo env vault suppress --repo-path C:\path\to\repo --target .env --variable OPENAI_API_KEY --json

Reveal an Env Vault value only when deliberate:

go run ./cmd/instantrepo env vault reveal --id 123 --confirm-reveal --json

Show shell and bridge contract metadata:

go run ./cmd/instantrepo shell info --json

Show Env Pattern Contribution settings:

go run ./cmd/instantrepo settings contribution get --json

Save Env Pattern Contribution settings:

go run ./cmd/instantrepo settings contribution save --file C:\path\to\settings.json --json

Record Env Pattern Contribution consent:

go run ./cmd/instantrepo settings contribution consent --public-enabled true --json

Clear queued Env Pattern Contribution records:

go run ./cmd/instantrepo settings contribution clear-queue --json

Show AI Env Review settings:

go run ./cmd/instantrepo settings ai-env-review get --json

Save AI Env Review settings:

go run ./cmd/instantrepo settings ai-env-review save --file C:\path\to\settings.json --json

Legacy prepare .env:

go run ./cmd/instantrepo -path C:\path\to\repo -step create-env-file -approve

Use isolated app metadata:

go run ./cmd/instantrepo --app-data-dir C:\temp\instantrepo-app-data repo analyze --path C:\path\to\repo

INSTANTREPO_APP_DATA_DIR also works for CLI and Wails launches. The app data path must be absolute and must not point at home, drive root, repo root, target repo, or a folder inside the target repo. Bad overrides fail closed instead of silently using normal app metadata. Commands that open the Local App Database create the directory; metadata-only commands such as version and shell info validate the path but do not create it. Env Vault OS credential keys are scoped to the Local App Database identity, so temp app data cannot overwrite, reveal, or delete the default app-data vault credentials by reusing the same SQLite row IDs.

Legacy flags still work for existing scripts:

go run ./cmd/instantrepo -path C:\path\to\repo
go run ./cmd/instantrepo -path C:\path\to\repo -step install-node-deps -approve

OpenDirectory() is desktop-only. CLI commands use explicit --path, --destination, and --repo-path arguments instead of opening a folder picker.

API

Start server:

go run ./cmd/instantrepo -serve :8080

Analyze:

curl -X POST http://localhost:8080/analyze ^
  -H "Content-Type: application/json" ^
  -d "{\"repoUrl\":\"https://github.com/user/repo\"}"

Run step:

curl -X POST http://localhost:8080/execute ^
  -H "Content-Type: application/json" ^
  -d "{\"localPath\":\"C:\\path\\to\\repo\",\"stepId\":\"install-node-deps\",\"approveRisky\":true}"

Test

Run Go tests:

go test ./...

Build frontend:

cd cmd/instantrepo-wails/frontend
bun run build

Run frontend behavior tests:

cd cmd/instantrepo-wails/frontend
bun test

Check private QA no-ship guard:

go test ./internal/command -run TestPrivateQALocalWorkspaceRemainsIgnored
git check-ignore .qa-local/

Manual MVP test plan live in test/TEST_PLAN.md. Repo tracking sheet live in test/repo-matrix.csv.

Trust Model

InstantRepo trust stronger evidence first:

1. Lockfiles and config.
2. Manifests and runtime files.
3. Env templates and Docker Compose files.
4. README.md as support.
5. Guessing.

README commands can help, but do not beat manifest-backed commands.

Active Roadmap

Completed Env Draft foundation:

1. #15 PRD: Catalog-driven Env Drafts and Vault-backed Credentials is the parent track.
2. #16 Env Draft model + safe Save All is done.
3. #17 Env target inference is done.
4. #18 Env Default Catalog is done.
5. #19 App Topology + allocator is done.
6. #20 Structured Env UI is done.
7. #21 User Env Vault backend is done.
8. #22 Env Vault Manager is done.
9. #23 Env Pattern Contribution is done.
10. #24 AI Env Review + Env Patch is done.

Architecture cleanup also landed after #20:

• #25 Deepen setup architecture after Env Draft foundation
• #26 Deepen setup safety scan with ignored generated folders
• #27 Deepen Env Draft foundation interfaces

Current CLI mirror roadmap:

1. #34 PRD: Mirror Wails app operations through production-safe CLI
2. #35 CLI foundation, JSON contract, and app-data isolation is done.
3. #36 Repository analyze, import, preflight, and execute CLI is done.
4. #37 Env Draft generate and save CLI is done.
5. #38 Installed repo history and diagnostics CLI is done.
6. #39 Env Vault secret-safe CLI is done.
7. #40 Settings and bridge contract metadata CLI is done.
8. #41 CLI mirror and private QA convention docs has local docs in this workspace; verify tracker state before closing.

Next Work

• Review local docs/code against GitHub issue state, then close #41 and parent #34 only after human check.
• Keep .qa-local/ private and ignored; do not commit private QA harness files.
• Add more manifests, package managers, and topology detectors.
• Package desktop app for Windows and later macOS.
• Add optional reputation scan for risky files.