nite/quadlet-migrator-skill
1
0
Fork 0
mirror of https://github.com/bestnite/quadlet-migrator-skill.git synced 2026-04-04 01:23:28 +00:00
Code Issues Activity

Refine finalize review and output prompting rules.

Browse Source 
Align the Quadlet migrator skill with a conversation-based finalize flow, default current-directory output, and opt-in AutoUpdate planning only when fully-qualified registry images support it.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
nite
2026-04-04 06:30:26 +11:00
parent 068299e9b3
commit 17c5eb59a8
5 changed files with 102 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
references/deployment-notes.md
View File

@@ -4,11 +4,18 @@ Use this file when the user wants deployment-ready instructions alongside genera
## Delivery flow
1. Generate the reviewable artifacts in the current working directory.
2. Review the generated Quadlet files, env files, helper scripts, and any required repo-local support files or directories.
3. Use `install.sh` to copy only the reviewed Quadlet unit files into the chosen Quadlet directory.
4. Use `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` to manage the deployed services.
5. Use `uninstall.sh` when the user wants to remove the installed reviewed Quadlet unit files without broad Podman cleanup.
For `design` mode, stop after the user reviews the finalize snapshot in conversation.
For `generate` mode, continue only after the user has reviewed and confirmed the finalize snapshot or requested edits.
1. Generate the reviewable artifacts in the current working directory by default, or in another user-requested output directory.
2. Resolve high-impact planning questions with the user before freezing the design.
3. Review the finalized design snapshot together with the generated Quadlet files, env files, helper scripts, and any required repo-local support files or directories.
4. Use `install.sh` to copy only the reviewed Quadlet unit files into the chosen Quadlet directory.
5. Run the appropriate `daemon-reload` command.
6. Use `start.sh`, `stop.sh`, and `restart.sh` to manage the deployed services.
7. Use `uninstall.sh` when the user wants to remove the installed reviewed Quadlet unit files without broad Podman cleanup.
Do not start execution until the user has reviewed and confirmed the finalize snapshot or requested edits.
## Apply target directory
@@ -28,16 +35,14 @@ See `podman-systemd.unit.5.md` for the full search-path matrix.
- `install.sh`: canonical apply script; copy only reviewed Quadlet unit files into the selected Quadlet target directory
- do not generate a separate `apply.sh` by default; reserve that alternate name only when the user explicitly asks for it
- `uninstall.sh`: remove the installed reviewed Quadlet unit files from the selected Quadlet target directory, stopping affected services first when needed
- `reload.sh`: run the appropriate `daemon-reload` command after installation changes
- `start.sh`: start the generated units; when the topology uses a `.pod`, start the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of also starting each child container service individually
- `stop.sh`: stop the generated units; when the topology uses a `.pod`, stop the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of duplicating per-container stop commands for its child containers
- `restart.sh`: restart the generated units after reload or config changes; when the topology uses a `.pod`, restart the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of also restarting each child container service individually
- `install.sh` must not start, stop, restart, or reload services as a side effect
- `uninstall.sh`: remove the installed reviewed Quadlet unit files from the selected Quadlet target directory
- `uninstall.sh` should stop affected services before removing their installed unit files, and should not delete support files from the current-directory deliverable set, unrelated files, shared directories, named volumes, images, or Podman objects unless the user explicitly asks for broader cleanup
- `reload.sh`: run only the appropriate `daemon-reload` command after installation changes
- `start.sh`, `stop.sh`, `restart.sh`: manage services only and must not silently install or overwrite reviewed files
- when a generated topology includes `<name>.pod` plus child containers linked with `Pod=<name>.pod`, helper scripts should use the pod service as the lifecycle entrypoint; derive that service name from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of duplicating per-container lifecycle commands for child units
Keep installation separate from service-management scripts so the user can review generated files before applying them.
`install.sh` should copy reviewed Quadlet unit files into the chosen Quadlet target directory only, and should not start, stop, restart, or reload services as a side effect.
`uninstall.sh` should remove only the installed reviewed Quadlet unit files, stop affected services before removal when needed, and leave the support files in the current-directory deliverable set, unrelated files, shared directories, named volumes, images, and Podman objects alone unless the user explicitly asks for broader cleanup.
`reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` should not silently install or overwrite reviewed files.
Do not use `ServiceName=` as an application connection target. It controls the generated systemd unit name only. When services communicate over a shared network outside a single pod namespace, prefer container names, pod names, or explicit `NetworkAlias=` values.
Within a single pod, use `127.0.0.1` / `localhost` for container-to-container communication instead of generating `AddHost=` entries whose purpose is sibling-container discovery.
If a service inside the pod must accept connections from sibling containers, ensure its effective listen address is reachable within the shared pod namespace, typically `127.0.0.1` or `0.0.0.0`. When the upstream service exposes this through environment variables or similar runtime configuration, preserve or generate that setting explicitly.
@@ -57,11 +62,12 @@ Execution checklist template before install:
- [ ] all reviewed artifacts are present in the current-directory deliverable tree
- [ ] required support files and directories are included alongside the Quadlet and env artifacts
- [ ] unit files map to the intended Quadlet directory
- [ ] every `EnvironmentFile=` path resolves to an actual reviewed file
- [ ] support files remain in the current-directory deliverable tree at the absolute paths referenced by mounts and scripts
- [ ] startup-critical env keys are present in the final env sources
- [ ] startup-critical env keys are present, or explicitly marked as unresolved placeholders
- [ ] any unresolved values are clearly marked as intentionally non-runnable placeholders
- [ ] service-management scripts operate on the same reviewed artifact set that will be installed
- [ ] service-management scripts operate on the same reviewed artifact set that finalize approved
- [ ] runnable-output gate passed before describing the result as runnable
## Rootless operational notes
@@ -95,7 +101,7 @@ Use the timeout especially when first start may need to pull large images or bui
## Useful optional enhancements
- `AutoUpdate=registry` for opt-in automatic image refresh workflows
- `AutoUpdate=registry` for opt-in automatic image refresh workflows when the approved image strategy uses fully qualified registry images
- explicit `.volume` or `.network` units when the user wants declarative infrastructure instead of implicit Podman objects
## Output language