npm package: @magray/quickstart-bootstrap
Description: Flagship bootstrap runtime for Stardev projects
Latest version: 0.3.4

# Stardev Bootstrap

> Opinionated, deterministic quality gate you can drop into any repository in under a minute.

---

## Why Stardev Bootstrap

- **Instant quality guardrails** – one command wires up formatting, linting, testing, duplication, complexity, contracts, SBOM and security checks.
- **Deterministic by design** – pinned toolchain, `npm ci --no-audit --no-fund`, manifest-based delivery with automatic pruning of obsolete files.
- **Designed for agents** – fast-review mode for local feedback, full quickstart for CI, smoke automation for releases, rich logs for RCA.
- **Stack-aware installs** – npm/pip/go/rust/C++ toolchains are only provisioned when the target repository actually uses them.

| Capability | Description | Key Artefacts |
|------------|-------------|---------------|
| Full quickstart gate | `make bootstrap-test` (or CLI `init --with-test`) runs fmt/lint/test/race/dup/complexity/guard/security/sbom | `reports/verify.json`, `reports/logs/<ts>.log` |
| Fast review | `make bootstrap-make TARGET=fast-review` (or CLI `init --fast-review`) executes fmt + lint + dup + complexity + guard; the CLI primes the toolchain with `make deps` on first run | `reports/logs/<ts>.log` |
| Release automation | `make bootstrap-dist`, `make bootstrap-release-notes`, `stardev-bootstrap smoke-release` | `artifacts/*.tar.gz`, `reports/releases/latest.{md,json}` |
| Manifest v2 | `reports/bootstrap/manifest.v2.json` tracks hashes, removes obsolete files, preserves intentional edits | `reports/bootstrap/manifest.v2.json` |
| Toolchain caching | npm/pip/go installs happen once; refresh via `FORCE_*_DEPS=1 make deps` | `tools/state/*.stamp` |
| Security posture | `make security`, SBOM via Syft, pip audit patching, smoke script for missing pip-audit | `reports/security.json`, `reports/sbom.cdx.json` |

---

## Repository Layout

```
bootstrap/
  docs/                    # Flagship guides & prompts
  quickstart-runtime/      # Submodule: flagship-universal bootstrap runtime
Makefile                   # Host-level orchestration
README.md                  # You are here
scripts/                   # CI helpers, dev wrappers
```

---

## Getting Started (3-Step Flow)

1. **Deliver payload + gate**
   ```bash
   npx @magray/quickstart-bootstrap init --with-test
   ```
   > Локально (до публикации в npm) используйте `make agent-init` — тарболл собирается в `artifacts/`, а CLI запускается через `scripts/dev/npx-bootstrap.sh` с автоматическим фоллбеком (кеш держит последние 3 tarball; настройка через `KEEP_LOCAL_TARBALLS`).
2. **Working on large repos?** (after one full quickstart) run locally:
   ```bash
   npx @magray/quickstart-bootstrap init --fast-review
   ```
   > Для локальных правок аналог: `make agent-fast-review`.
   > Reuses cached toolchain. Always follow up with the full quickstart in CI.
3. **Release**
   ```bash
   make release PUBLISH=1
   ```
   > Команда выполняет review → pack → smoke → dist → release notes → npm publish (при `PUBLISH=1`; без флага публикация пропускается). Все артефакты и логи складываются в `artifacts/` и `reports/releases/`.

> Developing the package itself? Use `./scripts/dev/npx-bootstrap.sh <cmd>` or build a local tarball via `npm pack` and reference it as `npx @magray/quickstart-bootstrap@file:./artifacts/<pack>.tgz`.

---

## Installation Requirements

- Node.js ≥ 20 (auto-installs locally in `tools/node` if missing; cached per version).
- Python ≥ 3.10 with `venv` module.
- Git + `rsync` (or fallback to `cp -a`).
- Docker optional – only used for SBOM when Syft is unavailable.

---

## CLI Reference

| Command | Purpose | Typical Use |
|---------|---------|--------------|
| `npx @magray/quickstart-bootstrap init --with-test` | Deliver payload, update manifest, run full quickstart gate | First bootstrap, CI pipelines |
| `npx @magray/quickstart-bootstrap init --fast-review` | Deliver payload + fast gate (fmt/lint/dup/complexity/guard); при отсутствии toolchain CLI автоматически выполняет `make deps` | Local feedback loops |
| `npx @magray/quickstart-bootstrap init --force` | Re-delivery overwriting local edits | Controlled resets after backup |
| `stardev-bootstrap test` | `npm ci` + `make bootstrap-test` | Ad-hoc verification |
| `stardev-bootstrap dist` | Proxy to `make bootstrap-dist` | Packaging |
| `stardev-bootstrap notes` | Proxy to `make bootstrap-release-notes` | Release documentation |
| `stardev-bootstrap smoke-release` | npm pack → install → `init --with-test` smoke | Final release validation |
| `stardev-bootstrap cleanup` | Remove delivered payload & manifests | Tear-down |

---

## Make Targets Cheat Sheet

| Category | Target(s) | Notes |
|----------|----------|-------|
| Agent | `agent-init`, `agent-fast-review`, `agent-help`, `agent-smoke` | Dev-friendly wrappers over `scripts/dev/npx-bootstrap.sh`; `agent-smoke` всегда использует локальный тарболл |
| Bootstrap | `bootstrap-sync`, `bootstrap-test`, `bootstrap-dist`, `bootstrap-release-notes` | High-level driver commands |
| Runtime review | `make quickstart`, `make fast-review`, `make review` | Full vs fast gate |
| Release | `make release [PUBLISH=1]` | Review → pack → smoke → dist → notes (+ npm publish при `PUBLISH=1`) |
| Tooling | `make deps`, `make doctor`, `make clean`, `make bootstrap-clean(-logs)` | Environment hygiene |
| Security | `make security`, `make security-smoke-missing-pip-audit`, `make sbom` | Security posture |
| Documentation | `make bootstrap-release-notes`, `make contracts`, `make bench-collect` | Artefact generation |

> Планирование и контроль: актуальные эпики и действия ведутся в `todo.machine.md`.

> Full target list: `make help` or `make bootstrap-make TARGET=help`.

---

## Release Checklist (Manual Fallback)

> Основной путь — `make release` (опционально с `PUBLISH=1`). Список ниже остаётся как ручная альтернатива.

| Step | Command | Output |
|------|---------|--------|
| 1 | `make bootstrap-sync` | Submodule synced |
| 2 | `make bootstrap-test` | Full gate report (`reports/verify.json`) |
| 3 | `make bootstrap-dist` | Tarball + SHA (`artifacts/…`) |
| 4 | `make bootstrap-clean-all` | Clean caches/logs |
| 5 | `make bootstrap-release-notes` | `reports/releases/latest.{md,json}` |
| 6 | `stardev-bootstrap smoke-release` | Automated smoke log |
| 7 | `npm publish` | Published package |

---

## How Manifest v2 Works

```
reports/bootstrap/manifest.v2.json
└── files
    ├── <relative-path> : <sha256>
    └── …
```

- On delivery, SHA256 hashes are stored for every file.
- If a file is missing in the new payload and unchanged locally, it is deleted (auto-prune).
- Local modifications are preserved and highlighted as warnings.
- Legacy `reports/bootstrap-manifest.json` is removed automatically once v2 is written.

---

## CI Pipelines Overview

| Workflow | Purpose | Key Steps |
|----------|---------|-----------|
| `bootstrap-ci.yml` | Main quality gate | checkout, `bootstrap-test`, `bootstrap-dist`, cleanup, release notes |
| `quickstart-sync.yml` | Keep runtime submodule fresh | cron/dispatch → test → clean logs → commit |
| `bootstrap-release.yml` | Release with artefacts | full gate, pack, dist, notes, optional npm publish |
| `bootstrap-smoke.yml` | Verify published package | install latest release, run `init --with-test` |

Security smoke (`scripts/ci/security_smoke.sh`) reproduces the behaviour when `pip-audit` is missing, ensuring the gate fails loudly.

---

## Troubleshooting

| Symptom | Possible Cause | Resolution |
|---------|----------------|------------|
| Manifest warnings about preserved files | Local edits differ from delivered hash | Review diffs, keep or back up then rerun with `--force` |
| `npm ci` reruns on every init | Lockfile missing / stack действительно использует JS | Commit `package-lock.json` в downstream или принимайте установку | 
| Syft downloads repeatedly | Using older CLI (pre caching) | Upgrade to the latest published CLI |
| `smoke-release` fails | Tarball not built or gate failure | Inspect `reports/logs/<ts>.log`, rerun `make fast-review` |
| `init --fast-review` fails with ENOENT | Пакет не опубликован/нет локального `npm pack` | Выполните `npm pack` и используйте `@file:<path>` или установите свежий релиз из npm |
| Need to refresh cached toolchains | Fresh dependencies required | `FORCE_NODE_DEPS=1 FORCE_PY_DEPS=1 make deps` |

---

## Useful References
- [Usage guide](bootstrap/docs/USAGE.md)
- [Agent prompt](bootstrap/docs/AGENTS-General-Prompt.md)
- [Legacy agent prompt (archived)](bootstrap/docs/AGENTS-старый.md)
- [Quickstart runtime](bootstrap/quickstart-runtime/README.md)

---

Built for flagship+++ quality — automate ruthlessly, measure everything, and keep the developer (human or agent) in flow.