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

   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:

   npx @magray/flagship init --fast-review

   Для локальных правок аналог: make agent-fast-review. Reuses cached toolchain. Always follow up with the full quickstart in CI.

3. Release

   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
• Agent prompt
• Legacy agent prompt (archived)
• Flagship runtime

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