@boxes-dev/dvb-runtime 1.0.1007 → 1.0.1009

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.
@@ -33,9 +33,13 @@ agentThreads:
33
33
  # include: ["<thread-id>", ...]
34
34
  ```
35
35
 
36
- `dvb agent-init detect agent-threads` lists detected threads (id, backend,
37
- title). History can be large — import only what the user asks for; `none`
38
- is the sensible default.
36
+ `dvb agent-init detect agent-threads --project <path>` lists conversations for
37
+ the selected repositories and their Git worktrees. `start` uses that same
38
+ scope for the manifest's suggested conversation inventory. Use
39
+ `detect agent-threads --all` to include other projects and conversations whose
40
+ project is unknown; their ids can be selected normally. Add `--json` for the
41
+ complete list when the text display is shortened. History can be large, so
42
+ import only what the user asks for; `none` remains the default.
39
43
 
40
44
  Done means: the `include` list reflects the user's choices, and any
41
45
  can't-copy items have been mentioned to them.
@@ -33,5 +33,9 @@ artifacts:
33
33
  Present to the user with sizes (from `detect untracked`) so they can weigh
34
34
  bundle cost. When in doubt, ask — the user knows what's precious.
35
35
 
36
+ An individual file can use `from: <staging-relative-file>` to send edited
37
+ contents without changing the original. This also works for binary files.
38
+ For a folder, select the folder itself; edited-copy sources must be files.
39
+
36
40
  Done means: everything untracked-and-irreplaceable (or slow to recreate) is
37
41
  listed or deliberately excluded; nothing rebuildable is listed.
@@ -9,9 +9,11 @@ go in the manifest or in chat.
9
9
  What belongs where:
10
10
 
11
11
  - `files.env`: files of environment variables (`.env`, `.env.local`,
12
- `.env.development.local`, ...) that are untracked/gitignored and required
13
- for local development. Do not include committed templates like
14
- `.env.example`.
12
+ `.env.development.local`, ...) required for local development, including
13
+ files outside the project. Use a project-relative path, an absolute path,
14
+ or `~/...`. Usually these are untracked or Git-ignored. Committed templates
15
+ like `.env.example` already travel with the repository and ordinarily do
16
+ not need an explicit copy.
15
17
  - `files.other`: other untracked files with secrets or local config — CLI
16
18
  and SDK credentials kept in-repo, service-account JSON files, local
17
19
  certificates, tool config the project expects to be present.
@@ -54,5 +56,8 @@ Present to the user as a short table (file → why it's needed → secret vars
54
56
  by name). Ask about anything you're unsure belongs — the user knows which
55
57
  credentials they're comfortable copying.
56
58
 
57
- Done means: every untracked file local dev needs is listed (or the lists are
58
- explicitly empty), and nothing tracked-in-git is listed.
59
+ Done means: every extra environment or secret file local development needs is
60
+ listed or deliberately omitted. These entries are explicit choices; they are
61
+ not filtered by the desktop scan's rules. Removing an entry will remove its
62
+ explicit copy, but repository copying or the separate `untracked` selection
63
+ may still include the file.
@@ -46,6 +46,14 @@ Present to the user as two short lists; for `configs`, call out that these
46
46
  files are copied and confirm each one. The user may know of tools you can't
47
47
  detect — ask.
48
48
 
49
+ For an edited copy, add `from: <staging-relative-file>` to the config entry.
50
+ The original will stay untouched. Shell startup files `~/.bashrc` and
51
+ `~/.zshrc` are optional: list each one only if the user chooses to import it.
52
+ Use an edited copy to remove laptop-only commands. The remote setup agent
53
+ will adapt the selected content for Linux in separate imported shell files,
54
+ preserving the Template box's managed shell setup. Omitted shell files will
55
+ not be imported automatically.
56
+
49
57
  Done means: the Template box's setup agent could install every needed tool from
50
58
  `dependencies`, and every outside-project file local dev reads is either
51
59
  listed in `configs` or deliberately excluded.
@@ -41,6 +41,11 @@ everything detectable (agent config, repos, untracked-file defaults), plus
41
41
  the live instance-type catalog and the team's current default. It prints the
42
42
  manifest path — that file is now the working document.
43
43
 
44
+ Read any project-overlap or skipped-repository explanations printed by `start`.
45
+ Explain them to the user during review and confirm the intended project scope.
46
+ `check` repeats these explanations in the launch summary; an overlap does not
47
+ automatically prevent setup.
48
+
44
49
  ## Phase 3: Investigate and compose
45
50
 
46
51
  Fill in every section marked `TODO(agent)`. Each has a guide:
@@ -56,6 +61,12 @@ Set `githubAccess: ssh` and the GitHub `gitSsh` rows to setup only when the user
56
61
  chooses the SSH alternative. GitLab and other origins continue to use their
57
62
  seeded `gitSsh` entries.
58
63
 
64
+ Separately, `dvb agent-init github cli status` shows whether boxes.dev will
65
+ sign the `gh` command into the user's connected GitHub account on their boxes.
66
+ Use `github cli enable` or `github cli disable` only after the user chooses
67
+ to change it. This changes their existing account setting across projects;
68
+ it is separate from repository pull/push access and is not a manifest field.
69
+
59
70
  Review `devboxLifecycle` even when its seeded Git refresh is correct. Add a
60
71
  teardown script only for cleanup that must happen before a devbox is removed.
61
72
  If the Template box needs ongoing upkeep, design `templateMaintenance.script`
@@ -112,7 +123,10 @@ uninterrupted.
112
123
  Template box on their account.
113
124
  3. `dvb agent-init run` — executes end to end: package (including fresh
114
125
  database dumps), encrypt, upload, provision, remote setup. It streams
115
- progress lines; relay the interesting ones. Expect several minutes.
126
+ progress lines; relay the interesting ones. Expect several minutes.
127
+
128
+ If signing setup prints a public key, relay it with its Git-host registration
129
+ instructions. The user can retrieve these again with `dvb agent-init status`.
116
130
 
117
131
  If the manifest changes after `check`, `run` refuses until you re-check and
118
132
  re-confirm with the user.
@@ -12,7 +12,7 @@ gitSigning:
12
12
  for hardware-backed keys (YubiKey, FIDO, smartcard) or agent-only SSH
13
13
  keys — `run` reports if the copy can't work, in which case fall back to
14
14
  `create` or `skip`.
15
- - `create`: generate a fresh signing key on the Template box. The user must
15
+ - `create`: prepare a signing key locally and upload it to the Template box. The user must
16
16
  register its public key with their Git host for commits to show as
17
17
  verified.
18
18
  - `skip`: unsigned commits from the Template box.
@@ -25,3 +25,10 @@ is hardware-backed.
25
25
 
26
26
  This is a one-line decision in the manifest; the machinery (key detection,
27
27
  staging, warnings) runs during `run` and surfaces problems in its output.
28
+
29
+ `run` prints the public signing key and registration instructions for its Git
30
+ host. Relay those to the user. Retrieve them again with `dvb agent-init status`
31
+ (or `status --json`). Only public keys belong in this handoff; never print
32
+ private keys. Signing identifies the signer of a commit and is separate from
33
+ permission to pull or push. Setup can finish before host registration, but the
34
+ host will not recognize the new signature until the public key is registered.
@@ -51,24 +51,32 @@ gitSsh:
51
51
  `https://` URL, since the Template box authenticates over SSH.
52
52
  - `mode: skip` records that push/pull auth is intentionally absent.
53
53
 
54
+ The helper reads all selected repositories from the document, including child
55
+ paths such as `api` or `web`. It reuses one key and checks every repository
56
+ requesting SSH. If several hosts are listed, register the same public key on
57
+ each required host. Automatic GitHub access can remain enabled alongside SSH
58
+ for other hosts. Rows for repositories excluded by `project.repositories`
59
+ do not participate in setup.
60
+
54
61
  Setup happens BEFORE launch, during composition. It is interactive only when
55
62
  the key is not already registered:
56
63
 
57
- 1. `dvb agent-init git-ssh setup` (add `--convert-origin` to match the
58
- manifest) — creates or reuses the key and pre-checks access.
64
+ 1. Set each selected repository's SSH choice in the document, then run
65
+ `dvb agent-init git-ssh setup` to create or reuse the key and pre-check access.
59
66
  2. If it reports verified, stop here. The key is already registered; do not
60
67
  ask the user to add it again.
61
68
  3. If it reports pending, relay the printed key to the user with instructions
62
69
  for their host (GitHub:
63
- Settings → SSH keys, or repo → Settings → Deploy keys with write access;
70
+ Settings → SSH keys;
64
71
  GitLab: Preferences → SSH keys). Pending is the normal state for a new key,
65
72
  not a setup error.
66
73
  4. After the user confirms, `dvb agent-init git-ssh verify` — retries are
67
74
  fine; run it until it reports verified.
68
75
 
69
- `run` proceeds with whatever state was recorded; an unverified setup means
70
- the Template box may fail to pull until the key is registered, so finish
71
- verification first when the user wants sync.
76
+ `check` and `run` require verification for the requested SSH repositories.
77
+ Changing a repository target requires verification again. Verification checks
78
+ read access; ensure the registered key also has write permission if the user
79
+ wants to push. An error names the repository that could not be accessed.
72
80
 
73
81
  Investigation is trivial: `git remote get-url origin` per repo (the seeded
74
82
  manifest already annotates origins). The real work is the user
@@ -9,28 +9,46 @@ Rules:
9
9
 
10
10
  - New manifests use `version: 3`; version 1 and version 2 manifests remain
11
11
  supported and are not rewritten. Every top-level section must be present.
12
- Deleting an entry excludes it; an explicitly empty list means
12
+ Deleting an entry removes that explicit copy; repository copying and the
13
+ separate `untracked` selection can still include the file. An empty list means
13
14
  "investigated, nothing needed"; a leftover `# TODO(agent)` comment blocks
14
15
  `check`.
15
- - Paths in `files`, `artifacts`, and `gitSsh` are relative to `project.root`.
16
- `external.configs` paths may live outside the project (`~/...` is allowed).
16
+ - Paths in `files.other`, `artifacts`, and `gitSsh` are relative to `project.root`.
17
+ `files.env` and `external.configs` may also use absolute paths or `~/...`
18
+ for files outside the project.
17
19
  Lifecycle and maintenance scripts are inline shell text, not file paths.
18
20
  - Never put secret values anywhere in this file. Env vars are listed by
19
21
  name with `secret: true/false`.
22
+ - Use `project.repositories` to select repository paths (`["."]` for a
23
+ repository at the project root). Use `project.rootEntries` separately for
24
+ ordinary files and folders alongside child repositories. For example,
25
+ `repositories: [api, web]` and `rootEntries: [package.json, scripts]` will
26
+ copy those two repos and those two root entries. Removing a repo from this
27
+ selection excludes it from access setup and general copying. Older documents
28
+ without these fields retain the existing project selection.
29
+ Update startup scripts and maintenance watches when changing the selection;
30
+ setup will not rewrite your shell commands.
31
+ - Set `untracked.copy` independently of `localChanges.copyDirty`. Custom
32
+ rules can use `base: defaults` to retain normal exclusions or `base: all`
33
+ to start from all eligible files. Older documents that omit these fields
34
+ keep their previous meaning; see the untracked guide for examples.
20
35
  - Comments are encouraged — annotate entries with why they're included so
21
36
  the user understands the plan at a glance.
22
37
  - To send an **edited** copy of a file without touching the real one, put
23
38
  the edited copy in the staging folder (printed by `start`) and set
24
39
  `from: <staging-relative-path>` on the entry. Useful for redacting a
25
- variable the Template box shouldn't get.
40
+ variable the Template box shouldn't get. This works for `files.env`,
41
+ `files.other`, `external.configs`, and individual files in `artifacts`.
42
+ It copies the file's exact contents without changing the original;
43
+ `from` does not support directories.
26
44
 
27
45
  Sections (each has its own guide topic):
28
46
 
29
47
  | Section | Meaning | Guide |
30
48
  | --- | --- | --- |
31
- | `project` | Pinned root, project name, and user-approved instance type | (seeded catalog; agent asks user) |
49
+ | `project` | Root, repository/root-entry selections, name, and user-approved instance type | (seeded catalog; agent asks user) |
32
50
  | `agents.runtime` | Coding agents configured on the Template box | (seeded) |
33
- | `files.env` / `files.other` | Untracked env/secret files to copy | env-files |
51
+ | `files.env` / `files.other` | Explicit environment/secret file copies | env-files |
34
52
  | `external.dependencies` / `.configs` | Outside tools/services + their config files | external |
35
53
  | `artifacts` | Other untracked files worth copying | artifacts |
36
54
  | `databases` | Local databases to dump and restore | databases |
@@ -5,32 +5,42 @@ named files:
5
5
 
6
6
  ## `localChanges.copyDirty`
7
7
 
8
- Whether uncommitted worktree changes (staged/unstaged edits) are carried
9
- over. Default true — the Template box should look like the user's machine does
10
- right now. Set false only if the user prefers a clean checkout.
8
+ Whether staged and unstaged edits to tracked files will be copied. The default
9
+ is true. Set false if the user wants the committed versions of those files.
11
10
 
12
11
  ## `untracked`
13
12
 
14
- Everything untracked in git that isn't already covered by `files` or
15
- `artifacts` entries. Two modes:
13
+ Files Git lists as untracked, excluding Git-ignored files, that aren't already
14
+ covered by named setup-file entries. Set `copy: true` or `copy: false`
15
+ independently of `localChanges.copyDirty`. For older documents without `copy`,
16
+ this choice follows `localChanges.copyDirty`, preserving their behavior.
17
+ Named setup files keep their own selections. Two modes:
16
18
 
17
19
  - `mode: defaults` (recommended): include untracked files, minus
18
20
  well-known dependency/cache/build folders (node_modules, venvs, build
19
21
  output, caches). This matches what most users want.
20
- - `mode: custom`: hand-picked with gitignore-style globs:
22
+ - `mode: custom`: add include/exclude patterns. Use `base: defaults` to keep
23
+ the normal exclusions, or `base: all` to start from all eligible files.
24
+ Omitting `base` retains the older custom behavior: all eligible files.
21
25
 
22
26
  ```yaml
23
27
  untracked:
28
+ copy: true
24
29
  mode: custom
30
+ base: defaults
25
31
  include: ["assets/fixtures/**"] # force-include even if excluded below
26
32
  exclude: ["**/*.mp4", "tmp"] # exclude matches (include wins on overlap)
27
33
  ```
28
34
 
29
- Anything matching neither list is included, like the defaults. Selection
30
- granularity follows the enumerated tree from
31
- `dvb agent-init detect untracked` — print it (with sizes and the
32
- default-excluded markers) before proposing a custom selection, and share the
33
- relevant numbers with the user.
35
+ Include patterns win over both exclusions and defaults. A folder pattern
36
+ applies to all its descendants. Rules cover the full eligible file list, even
37
+ when the display omits children of large folders. Patterns use file-path globs
38
+ such as `**/*.mp4`; they are not complete `.gitignore` files. A matching include
39
+ does not override Git's own ignore rules; select an ignored file through a
40
+ named setup-file entry when needed.
41
+
42
+ Print `dvb agent-init detect untracked` with sizes and default exclusions
43
+ before proposing rules, and share relevant counts and sizes with the user.
34
44
 
35
45
  Size limits: the bundle blocks above 15GB uncompressed (25GB combined). If
36
46
  `check`/`run` reports a too-big bundle, this section (plus database dumps)