Skip to content

README.md

Latest commit

 

History

History
289 lines (204 loc) · 10.2 KB

README.md

File metadata and controls

289 lines (204 loc) · 10.2 KB

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 for quick analyze and step run.
  • 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 Direction

The current roadmap is to mirror Wails app operations through production-safe CLI subcommands. The 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 is done. Repository mirror work in #36 is done. Env Draft generate/save mirror work in #37 is done. The next public slice is #40, which adds settings and bridge contract metadata commands.

See #34 and remaining child issues #37-#41. See docs/adr/0003-use-private-local-qa-harness-with-safe-cli-surfaces.md for the private QA boundary.

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/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

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

Run one plan step:

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

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

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, repo root, target repo, or a folder inside the target repo. Bad overrides fail closed instead of silently using normal app metadata.

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

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

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:

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. #40 Settings and bridge contract metadata CLI
  6. #38 Installed repo history and diagnostics CLI
  7. #39 Env Vault secret-safe CLI
  8. #41 CLI mirror and private QA convention docs

Next Work

  • Start #40 settings and bridge contract metadata CLI mirrors.
  • 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.