nessar
d74dfb9938
4.7 KiB
name, description
| name | description |
|---|---|
| wizard | 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 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/anddocs/gitea-actions.mdfor 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>; runshellcheckif available.- Run
python3 test_wizard.pyfrom 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.