@boxes-dev/dvb-runtime 1.0.973 → 1.0.975

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.
@@ -47,7 +47,7 @@ Fill in every section marked `TODO(agent)`. Each has a guide:
47
47
  `env-files`, `external`, `artifacts`, `databases`, `app`, `untracked`,
48
48
  `git-ssh`, `git-signing`, `agent-config`.
49
49
 
50
- For GitHub repos, the v2 manifest defaults to `githubAccess: managed` and keeps
50
+ For GitHub repos, the manifest defaults to `githubAccess: managed` and keeps
51
51
  the seeded GitHub `gitSsh` rows in skip mode. If check says GitHub is not
52
52
  connected, run `dvb agent-init github connect`, have the user finish in the
53
53
  browser, and then re-run check. If the boxes.dev GitHub App is missing
@@ -56,6 +56,15 @@ Set `githubAccess: ssh` and the GitHub `gitSsh` rows to setup only when the user
56
56
  chooses the SSH alternative. GitLab and other origins continue to use their
57
57
  seeded `gitSsh` entries.
58
58
 
59
+ Review `devboxLifecycle` even when its seeded Git refresh is correct. Add a
60
+ teardown script only for cleanup that must happen before a devbox is removed.
61
+ If the Template box needs ongoing upkeep, design `templateMaintenance.script`
62
+ and its exact GitHub watch paths together: the watched changes should explain
63
+ why that script needs to run. Maintenance watches use boxes.dev GitHub App read
64
+ access independently of the `githubAccess` transport choice. Setup leaves the
65
+ maintenance schedule off, saves fresh baselines, and does not run maintenance
66
+ immediately.
67
+
59
68
  For `project.instanceType`, present every live option seeded in the manifest,
60
69
  ask the user which one they want, record that key, and remove its marker. The
61
70
  choice applies to the Template box and all of the project's devboxes and
@@ -79,9 +88,10 @@ mention its path so they can open it.
79
88
 
80
89
  Do not silently choose approval-sensitive options. Before `check`, explicitly
81
90
  confirm runtime agents and imported agent config/history, dirty and untracked
82
- files, databases, instance type, GitHub access, Git SSH/signing, and any
83
- instruction that lets the remote setup agent change tracked project files. It
84
- is fine to recommend defaults, but the user must make the choice.
91
+ files, databases, instance type, GitHub access, Git SSH/signing, devbox
92
+ lifecycle or Template maintenance configuration (including watch paths), and
93
+ any instruction that lets the remote setup agent change tracked project files.
94
+ It is fine to recommend defaults, but the user must make the choice.
85
95
 
86
96
  Git access may need outside action. For managed GitHub, use check to identify
87
97
  and complete connection, App repository access, or an account update. If
@@ -29,6 +29,12 @@ Set `githubAccess: ssh` to use the key flow below for GitHub. Set `skip` to
29
29
  leave GitHub push/pull unconfigured. Use null only when the project has no
30
30
  standard GitHub origin. GitLab and other hosts always use `gitSsh`.
31
31
 
32
+ `githubAccess` controls Git transport only. If `templateMaintenance.watches`
33
+ names a GitHub repository, `check` separately verifies boxes.dev GitHub App
34
+ read access for that repository so setup can save the initial watch baseline.
35
+ This is required even when Git transport uses SSH or is skipped; it does not
36
+ change the Template box's chosen push/pull transport.
37
+
32
38
  SSH manifest shape (one entry per repo; `.` is the project root):
33
39
 
34
40
  ```yaml
@@ -7,13 +7,14 @@ and edits it directly — keep it tidy and annotated.
7
7
 
8
8
  Rules:
9
9
 
10
- - New manifests use `version: 2`; version 1 manifests remain supported and are
11
- not rewritten. Every top-level section must be present. Deleting an
12
- entry excludes it; an explicitly empty list means "investigated, nothing
13
- needed"; a leftover `# TODO(agent)` comment blocks `check`.
10
+ - New manifests use `version: 3`; version 1 and version 2 manifests remain
11
+ supported and are not rewritten. Every top-level section must be present.
12
+ Deleting an entry excludes it; an explicitly empty list means
13
+ "investigated, nothing needed"; a leftover `# TODO(agent)` comment blocks
14
+ `check`.
14
15
  - Paths in `files`, `artifacts`, and `gitSsh` are relative to `project.root`.
15
16
  `external.configs` paths may live outside the project (`~/...` is allowed).
16
- `forkStartupScript.script` is inline shell text, not a path.
17
+ Lifecycle and maintenance scripts are inline shell text, not file paths.
17
18
  - Never put secret values anywhere in this file. Env vars are listed by
18
19
  name with `secret: true/false`.
19
20
  - Comments are encouraged — annotate entries with why they're included so
@@ -40,7 +41,8 @@ Sections (each has its own guide topic):
40
41
  | `gitSsh` | Git push/pull auth from the Template box | git-ssh |
41
42
  | `gitSigning` | Commit signing on the Template box | git-signing |
42
43
  | `agentConfig` / `agentThreads` | Claude/Codex config + history import | agent-config |
43
- | `forkStartupScript` | Optional inline shell commands for new devboxes; a safe Git refresh is recommended when the default branch is known | (seeded; edit or disable as desired) |
44
+ | `devboxLifecycle` | Startup and teardown commands for every devbox, with separate timeouts | (seeded; edit as desired) |
45
+ | `templateMaintenance` | Optional Template box upkeep script and the GitHub paths that should trigger it | (compose script and watches together) |
44
46
  | `setupNotes` | Free-form guidance for the remote setup agent | running |
45
47
 
46
48
  `project.instanceType` is seeded to the team's default, but it is not
@@ -50,7 +52,7 @@ validate that key against the current server catalog. Once remote setup starts,
50
52
  the project is pinned to it; changing the manifest cannot resize an in-progress
51
53
  or initialized project.
52
54
 
53
- `githubAccess` is one project-level choice in version 2. Keep `managed` for the
55
+ `githubAccess` is one project-level Git transport choice. Keep `managed` for the
54
56
  recommended connected-GitHub HTTPS path, choose `ssh` for the existing key
55
57
  flow, choose `skip` for intentionally absent GitHub push/pull, or use null only
56
58
  when no included repo has a standard github.com origin. With managed or skip,
@@ -59,6 +61,21 @@ convert its origin. With SSH, those rows use `mode: setup`. Non-GitHub rows keep
59
61
  their existing SSH meaning. Connection and repository ids never belong in the
60
62
  manifest; `check` derives them from current boxes.dev GitHub access.
61
63
 
64
+ Treat `templateMaintenance.script` and its `watches` as one design problem.
65
+ Write the script for the dependency, generated-file, or tooling changes that
66
+ will actually require upkeep, then watch the smallest exact paths that signal
67
+ those changes. Each `repository` is a detected project-relative repository
68
+ path (`.` for the root); each watched path is exact and relative to that
69
+ repository. Maintenance watches always require current boxes.dev GitHub App
70
+ read access, even when `githubAccess` uses SSH or skips Git transport.
71
+
72
+ Setup creates the maintenance policy with its schedule off, records a fresh
73
+ baseline for every watch, and does not run the script. A later watched change
74
+ or a schedule the user enables in Project settings can start the first run.
75
+ Keep `templateMaintenance: null` when the Template box needs no ongoing upkeep.
76
+ Use a nonempty teardown script only when devbox removal genuinely needs cleanup;
77
+ it is not a second maintenance hook.
78
+
62
79
  `setupNotes` is worth writing well: it goes verbatim to the agent that
63
80
  finishes setup on the Template box. Include install steps that aren't obvious
64
81
  from the repo, known gotchas, and a verification command ("`npm run dev`