nessar
d74dfb9938
CI / policy (push) Successful in 48s
CI / validate (push) Successful in 1m25s
CI / test (push) Successful in 3m43s
CI / build (push) Successful in 1m20s
CI / security (push) Successful in 1m31s
CI / benchmark (push) Failing after 5m52s
CI / images (push) Failing after 1m2s
CI / required (push) Failing after 1s
CI / policy (pull_request) Successful in 9s
CI / validate (pull_request) Successful in 1m6s
CI / test (pull_request) Successful in 3m30s
CI / benchmark (pull_request) Canceled after 3s
CI / build (pull_request) Successful in 1m5s
CI / security (pull_request) Successful in 1m27s
CI / images (pull_request) Successful in 2m24s
CI / required (pull_request) Successful in 5s
48 lines
4.7 KiB
Markdown
48 lines
4.7 KiB
Markdown
---
|
|
name: wizard
|
|
description: Generate an interactive Bash wizard for steps only a human can perform, such as dashboard setup or credential capture. Use for a requested manual procedure, not work the agent can complete directly.
|
|
---
|
|
|
|
# Wizard
|
|
|
|
A **wizard** walks a human through the manual parts of the requested procedure, captures values, and writes only to the selected destinations. Reuse the user's chosen service and CI platform; generating a wizard does not authorize running provisioning or publishing credentials.
|
|
|
|
Start from [template.sh](template.sh) for progress, confirmation gates, URL opening, hidden input, and persistence helpers. Adapt helpers when the selected destination requires it; verify changes with dummy data before handling real credentials.
|
|
|
|
The bundled dotenv helpers accept uppercase variable names and required, single-line values without apostrophes. They write private, single-quoted values so hashes, spaces, dollars, and backslashes survive; unsupported values or existing formats stop with an error. Confirm that the actual consumer supports this format. If it needs another dialect or multiline values, adapt both reading and writing and test a round trip through that consumer. EOF cancels the wizard; empty input keeps an existing value or fails if none exists.
|
|
|
|
A wizard is ephemeral by default — built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo.
|
|
|
|
## Process
|
|
|
|
### 1. Scope the procedure
|
|
|
|
Work out every manual step the human must take and every value that gets captured along the way. Read the repo first — don't ask cold:
|
|
|
|
- For setup: configuration examples, README, compose/framework configuration, and the actual CI files. This repository is hosted on Gitea; read `.gitea/workflows/` and `docs/gitea-actions.md` for the configured workflow and owner-activation requirements. Inspect secret names and references without displaying existing secret values. Include only values needed for the requested procedure, not every variable in the repository.
|
|
- For a migration or transition: the current state, the target state, and the irreversible actions between them.
|
|
|
|
Then show the user the ordered list of stages and the values each produces, and confirm — they may add, drop, or reorder.
|
|
|
|
**Done when:** every stage is named in order, and each captured value has a known source, selected destination (local file, configured secret store, or neither), and secrecy level.
|
|
|
|
### 2. Map each stage's journey
|
|
|
|
For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills — e.g. "Dashboard → Developers → API keys → Reveal test key → copy". Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs — never invent steps that may not exist.
|
|
|
|
**Done when:** every stage traces to concrete instructions a stranger could follow.
|
|
|
|
### 3. Author the wizard
|
|
|
|
Copy `template.sh` to the target path. Replace the example stages in dependency order, using `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, and `pause`/`confirm`. Set honest stage/time estimates. For CI secrets, use the selected platform's existing tooling or guide the human through its UI. Add a provider-specific writer only when needed and verify its local help, authentication, project scope, and secret-safe input mechanism first.
|
|
|
|
Open the URL before asking for its value, use `ask_secret` for secrets, and persist only to the selected destinations. Require a successful `confirm` before an irreversible action. Do not expose values in logs or command arguments. On an ambiguous remote write, check its result before retrying; on missing authority or repeated failure, stop that stage and report what remains. Keep each stage focused so needed instructions remain visible.
|
|
|
|
### 4. Verify and hand off
|
|
|
|
- `bash -n <script>`; run `shellcheck` if available.
|
|
- Run `python3 test_wizard.py` from this skill directory (requires Node for the dotenv consumer check). Source the generated script to test its helpers with dummy values in a temporary directory, without running the stages.
|
|
- `chmod +x <script>`.
|
|
- Don't run it end-to-end yourself — it opens browsers and blocks on human input. Check that each value lands in the selected destination and any CI variable name matches an actual reference. Test remote writers with stubs, never real credentials.
|
|
- Tell the user how to run it. For a requested repeatable setup path, link it from the relevant setup documentation. Commit only if requested, and do not execute the manual procedure merely because its script is complete.
|