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

   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:

   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

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

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