npm package: @magray/flagship
Description: Flagship bootstrap runtime for Stardev projects
Latest version: 0.3.9

# 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.
- **Runtime-only payload** – downstream repos receive just `.flagship/runtime/`; orchestration logic stays inside the installed package to avoid conflicts.

| Capability | Description | Key Artefacts |
|------------|-------------|---------------|
| Full quickstart gate | `npx @magray/flagship init --with-test` (or `npx @magray/flagship test`) runs fmt/lint/test/race/dup/complexity/guard/security/sbom inside the bundled runtime | `reports/verify.json`, `reports/logs/<ts>.log` |
| Fast review | `npx @magray/flagship init --fast-review` executes fmt + lint + dup + complexity + guard; CLI auto-primes toolchains with runtime `make deps` on first run | `reports/logs/<ts>.log` |
| Release automation | `npx @magray/flagship dist`, `npx @magray/flagship notes`, `flagship smoke-release` | `artifacts/*.tar.gz`, `reports/releases/latest.{md,json}` |
| Manifest v2 | `reports/flagship/manifest.v2.json` tracks hashes, removes obsolete files, preserves intentional edits | `reports/flagship/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

```
.flagship/
  runtime/                 # Flagship+++ runtime payload
  docs/                    # Flagship documentation & prompts
Makefile                   # Host-level orchestration
README.md                  # You are here
scripts/                   # CI helpers, dev wrappers
```

> Downstream delivery installs only `.flagship/runtime/`; остальное остаётся внутри `node_modules/@magray/flagship`.

---

## Getting Started (3-Step Flow)

1. **Deliver payload + gate**
   ```bash
   npx @magray/flagship 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/flagship 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/flagship@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/flagship init --with-test` | Deliver payload, update manifest, run full quickstart gate | First bootstrap, CI pipelines |
| `npx @magray/flagship init --fast-review` | Deliver payload + fast gate (fmt/lint/dup/complexity/guard); при отсутствии toolchain CLI автоматически выполняет `make deps` | Local feedback loops |
| `npx @magray/flagship init --force` | Re-delivery overwriting local edits | Controlled resets after backup |
| `flagship test` | Sync runtime → `npm ci` → `CI_STRICT=1 make preflight` + `review` | Ad-hoc verification |
| `flagship dist` | Runtime `make dist` + artefact/sha mirror into host repo | Packaging |
| `flagship notes` | Bundled JS generator → release notes (needs latest dist artefacts) | Release documentation |
| `flagship smoke-release` | npm pack → install → `init --with-test` smoke | Final release validation |
| `flagship 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` | Maintainer make wrappers; prefer `npx @magray/flagship …` |
| Runtime review | `make quickstart`, `make fast-review`, `make review` | Full vs fast gate |
| Release | `make release [PUBLISH=1]` | Maintainer pipeline (wraps flagship commands; prefer explicit `npx @magray/flagship …`) |
| 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`.

> `flagship dist` всегда зеркалирует свежий тарболл в два места: `artifacts/<name>.tar.gz` и `reports/artifacts/<name>.tar.gz.sha256`. Используйте эти файлы перед запуском `flagship notes`.

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

---

## Release Checklist (Manual Fallback)

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

| Step | Command | Output |
|------|---------|--------|
| 1 | `npx @magray/flagship init --fast-review` | Fast gate confirmation |
| 2 | `npx @magray/flagship init --with-test` | Full gate report (`reports/verify.json`) |
| 3 | `npx @magray/flagship smoke-release` | Automated smoke log (`reports/logs/<ts>_smoke.log`) |
| 4 | `npx @magray/flagship dist` | Tarball + SHA (зеркало в `artifacts/` и `reports/artifacts/`) |
| 5 | `npx @magray/flagship notes` | `reports/releases/latest.{md,json}` |
| 6 | `npm publish` | Published package |

---

## How Manifest v2 Works

```
reports/flagship/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 manifests (`reports/bootstrap/manifest.v2.json`, `reports/bootstrap-manifest.json`) are removed automatically after migration.

---

## 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` |
| Security step cannot reach registries | Offline / airgapped run | Set `ALLOW_OFFLINE_SECURITY=1` before `make review` (still fails in CI_STRICT) |

---

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

---

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