@boxes-dev/dvb-runtime 1.0.1092 → 1.0.1094

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -12,7 +12,7 @@ stable id; the seeded `include` list holds the recommended (default)
12
12
  selection with a label comment per item, and lists what was left out.
13
13
 
14
14
  - Reprint the inventory anytime: `dvb agent-init detect agent-config`
15
- (ids, categories, default flags).
15
+ (ids, categories, default flags, and why items are left out).
16
16
  - To change the selection, add/remove ids in `include`.
17
17
  - Items marked as credential files or "needs reauth" deserve an explicit
18
18
  user conversation: some remote/OAuth MCP servers can't be copied — they
@@ -20,7 +20,10 @@ selection with a label comment per item, and lists what was left out.
20
20
  (the user completes that from the desktop app).
21
21
 
22
22
  Present to the user as a grouped list (per agent: MCP servers, skills,
23
- settings, memory) and confirm anything credential-bearing.
23
+ settings, memory) and confirm anything credential-bearing. Mention skipped
24
+ Claude hooks during review: their commands may need scripts or tools that are
25
+ missing from the Template box, which can block Claude's replies. Add
26
+ `claude:hooks` if the user wants them included.
24
27
 
25
28
  ## `agentThreads`
26
29
 
@@ -146,12 +146,29 @@ it is separate from repository pull/push access and is not a manifest field.
146
146
 
147
147
  Review `devboxLifecycle` even when its seeded Git refresh is correct. Add a
148
148
  teardown script only for cleanup that must happen before a devbox is removed.
149
- If the Template box needs ongoing upkeep, design `templateMaintenance.script`
150
- and its exact GitHub watch paths together: the watched changes should explain
151
- why that script needs to run. Maintenance watches use boxes.dev GitHub App read
152
- access independently of the `githubAccess` transport choice. Setup leaves the
153
- maintenance schedule off, saves fresh baselines, and does not run maintenance
154
- immediately.
149
+ The generated Git block declares each selected repository's starting branch,
150
+ normally its remote default branch such as `main`. Keep those paths aligned with
151
+ `project.repositories` after narrowing the project. boxes.dev saves these
152
+ defaults separately and checks out fresh remote code before additional startup
153
+ commands. Confirm unknown branches instead of using the Template box's current
154
+ branch as the default. Keep dependency and service commands after the generated
155
+ block; do not add another Git reset or branch switch there.
156
+
157
+ Recommend Template maintenance when the project has dependencies, generated
158
+ code, or tooling that change over time; most projects do. New devboxes start
159
+ from the Template box's latest snapshot. Maintenance keeps that snapshot
160
+ current: it updates the Template box to the latest default branch, installs
161
+ locked dependencies, and refreshes tooling, then boxes.dev saves a new snapshot.
162
+ Design `templateMaintenance.script` and its exact GitHub watch paths together.
163
+ Watch the lockfiles, toolchain version files, and generated-code inputs that
164
+ make the script necessary. Don't watch application source; each matching push
165
+ wakes the Template box. Maintenance watches use boxes.dev GitHub App read
166
+ access independently of the `githubAccess` transport choice. Follow the
167
+ script requirements in the manifest guide. Setup leaves the maintenance
168
+ schedule off and saves fresh baselines. The remote setup agent tests the
169
+ script twice on the Template box before boxes.dev saves it. If the user
170
+ declines maintenance or the project has nothing to keep current, keep
171
+ `templateMaintenance: null` and say why in your review.
155
172
 
156
173
  For `project.instanceType`, present every live option seeded in the manifest,
157
174
  ask the user which one they want, record that key, and remove its marker. The
@@ -68,7 +68,7 @@ Sections (each has its own guide topic):
68
68
  | `gitSigning` | Commit signing on the Template box | git-signing |
69
69
  | `agentConfig` / `agentThreads` | Claude/Codex config + history import | agent-config |
70
70
  | `devboxLifecycle` | Startup and teardown commands for every devbox, with separate timeouts | (seeded; edit as desired) |
71
- | `templateMaintenance` | Optional Template box upkeep script and the GitHub paths that should trigger it | (compose script and watches together) |
71
+ | `templateMaintenance` | Recommended Template box upkeep script and the GitHub paths that should trigger it | (compose script and watches together) |
72
72
  | `setupNotes` | Free-form guidance for the remote setup agent | running |
73
73
 
74
74
  Record your current agent and exact model in `agents.setup` when you can verify
@@ -109,18 +109,57 @@ manifest; `check` derives them from current boxes.dev GitHub access.
109
109
  Treat `templateMaintenance.script` and its `watches` as one design problem.
110
110
  Write the script for the dependency, generated-file, or tooling changes that
111
111
  will actually require upkeep, then watch the smallest exact paths that signal
112
- those changes. Each `repository` is a detected project-relative repository
113
- path (`.` for the root); each watched path is exact and relative to that
114
- repository. Maintenance watches always require current boxes.dev GitHub App
115
- read access, even when `githubAccess` uses SSH or skips Git transport.
112
+ those changes, such as lockfiles and toolchain version files. Don't watch
113
+ application source; each matching push wakes the Template box. Each
114
+ `repository` is a detected project-relative repository path (`.` for the
115
+ root); each watched path is exact and relative to that repository. Maintenance
116
+ watches always require current boxes.dev GitHub App read access, even when
117
+ `githubAccess` uses SSH or skips Git transport.
118
+
119
+ A maintenance script must:
120
+
121
+ - Fetch and fast-forward each repository it depends on to its default branch,
122
+ then install locked dependencies and refresh generated files or tooling
123
+ without prompts.
124
+ - Exit nonzero with a clear message when a checkout has uncommitted changes or
125
+ is on another branch, when a required environment value is missing, or when
126
+ an update fails. Never skip an update and exit 0.
127
+ - Finish within `timeoutSeconds` and be safe to run again.
128
+ - Read secrets from boxes.dev managed environment files when needed. Never put
129
+ credentials in the script, and never save a snapshot from it; boxes.dev
130
+ saves the snapshot after a successful run.
131
+
132
+ The script runs with noninteractive bash and `set -e -o pipefail` from the
133
+ project root, with `HOME=/home/boxes` and `/opt/devbox-tools/bin` first on
134
+ PATH. Interactive `~/.bashrc` setup, such as nvm's shell hook, doesn't load, so
135
+ load any version manager the script needs explicitly. For example:
136
+
137
+ ```bash
138
+ branch=main
139
+ if [ "$(git branch --show-current)" != "$branch" ]; then
140
+ echo "The Template box is not on $branch." >&2
141
+ exit 1
142
+ fi
143
+ if [ -n "$(git status --porcelain --untracked-files=no)" ]; then
144
+ echo "The Template box has uncommitted changes." >&2
145
+ exit 1
146
+ fi
147
+ git fetch origin "$branch"
148
+ git merge --ff-only "origin/$branch"
149
+ npm ci
150
+ ```
116
151
 
117
152
  Set `templateMaintenance.timeoutSeconds` to an integer from 1 through 480
118
153
  seconds (at most 8 minutes).
119
154
 
120
- Setup creates the maintenance policy with its schedule off, records a fresh
121
- baseline for every watch, and does not run the script. A later watched change
122
- or a schedule the user enables in Project settings can start the first run.
123
- Keep `templateMaintenance: null` when the Template box needs no ongoing upkeep.
155
+ Setup creates the maintenance policy with its schedule off and records a
156
+ fresh baseline for every watch. The remote setup agent tests the script twice
157
+ under the maintenance runner's environment and saves any correction it makes;
158
+ setup does not start a maintenance run. A later watched change, **Run now** in
159
+ **Template maintenance** on the Template box page, or a schedule the user
160
+ enables can start the first run.
161
+ Keep `templateMaintenance: null` when the user declines maintenance or the
162
+ Template box needs no ongoing upkeep.
124
163
  Use a nonempty teardown script only when devbox removal genuinely needs cleanup;
125
164
  it is not a second maintenance hook.
126
165