@sagmans/dsh-tui 0.5.2 → 0.7.0

package/.agents/skills/dsh-tui-dogfood/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: dsh-tui-dogfood
+description: "Use when a dsh plugin checkout must be tested against a real profile without writing to the developer's live home: clone the home, relink only that plugin, and run or hand off the profile."
+---
+# Dogfood a dsh plugin checkout
+
+A fresh `DSH_HOME` misses the installed bundles, profile patch, settings, and themes.
+A run against the real home writes real sessions and state. Clone the source
+home and relink only the plugin under test inside the clone.
+
+From **any dsh plugin checkout root**, run the packaged helper:
+
+```sh
+~/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh --no-launch
+~/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh feat/plugin-fix -- --resume
+~/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh ../plugin-fix --dry-run
+```
+
+No target means the current checkout. A name matches its repository's worktree
+directory or branch tail. A path selects that checkout directly. The helper reads
+`package.json` for the plugin name; it never assumes `@sagmans/dsh-tui`. It
+runs `pnpm run build` only when the checkout declares a build script. It adds
+the bundle once if absent from the cloned profile, updates only its dependency,
+restores local links from `link:` specifications, and launches
+`dsh --profile tui` by default. The legacy
+`scripts/dogfood/run-tui-from-worktree.sh` remains available in dsh-tui and
+defaults to that script's checkout even when called elsewhere.
+
+| Need | Option |
+| --- | --- |
+| Inspect clone and linked bundle | `--status` |
+| Copy saved sessions for `--resume` | `--with-sessions` |
+| Copy credentials and settings only | `--fresh` |
+| Select profile, source home, or scratch home | `--profile NAME`, `--source-home DIR`, `--home DIR` |
+| Print plan without mutation | `--dry-run` |
+| Set up without starting dsh | `--no-launch` |
+| Discard and clone again | `--reseed` |
+| Remove matching scratch clone | `--clean` |
+| List checkout worktrees | `--list` |
+
+The helper ignores `$DSH_HOME` as source. Pass `--source-home "$DSH_HOME"`
+when you intend to clone it. The default scratch path includes the checkout
+name and path hash to avoid reuse across repositories.
+
+The clone contains copied credentials. Store it only in private scratch storage
+and remove it with `--clean`. Cleanup and reseed refuse nonmatching markers,
+source-home overlap, and home-root paths.
+
+External links are allowed only under `profiles/node_modules`,
+`profiles/*/node_modules`, and `profiles/*/.dsh-module-fallback/node_modules`.
+These package links can point to global packages or external checkouts, but
+never into the source home. Every other cloned link must stay inside the clone.
+An instruction file linked into a shared prompt tree (`AGENTS.md`, `CLAUDE.md`)
+is read only, so seeding copies it in as a regular file; a link to state the run
+may write — credentials, settings, storages, sessions, profiles — still stops the
+run. Mutable cloned files with multiple hardlinks are rejected. Never write test
+state through a package link.
+
+The old dsh-tui entry point still requires a prelisted bundle. Do not use
+`dsh plugin add` on a cloned profile with other bundles; it can drop them.
+
+Use `--status` to verify the existing bundles and the checkout `link:`
+dependency. In dsh-tui, drive a cloned profile with:
+
+```sh
+node tools/pty-drive.mjs --launcher "$(command -v dsh)" --home <clone> --prompt 'Reply with exactly: pong'
+```
+
+Dsh-tui source edits are invisible until `pnpm run build` updates `lib/`.
+Omit `--no-build` for real runs.
+
+If the checkout or source home was removed, use
+`--clean --home <clone> --source-home <original-source-path>`. Run from the
+checkout while it exists, or pass its path as the target from another
+directory. If the checkout was removed, run from any directory. Supply the
+original `--profile NAME` when it was not `tui`.
+
+Cleanup canonicalizes a missing source path only for `--clean --home` and
+still requires its marker to match. Orphan cleanup requires a private marker
+owned by the current user. It validates home, source, profile, and absent
+target, but cannot recheck a removed checkout.
+
+For home contents, storage, and cleanup details, read [references/home-state.md](references/home-state.md).

package/.agents/skills/dsh-tui-dogfood/references/home-state.md

@@ -0,0 +1,78 @@
+# What a ~/.dsh home holds, and what a dogfood run touches
+
+Read this when a dogfood run behaves differently from the developer's own
+profile. It gives the operational detail behind [../SKILL.md](../SKILL.md).
+
+## The entries
+
+| Entry | Kind | What reads or writes it |
+| --- | --- | --- |
+| `.credentials.yaml` | secret | the provider layer, at start-up; read-only |
+| `settings.yaml`, `settings.yaml.imported` | config | the `dsh-tui:` section: theme, tokens, dock, stash, prompt history |
+| `themes/` | data | created and watched at start-up; saving a file changes the live surface |
+| `prompt-history.json` | data | the editor's history recall; appended as prompts are sent |
+| `tui-stash/` | data | the parked-draft bank, one file per session, behind a lock |
+| `storages/` | data | durable plugin state |
+| `attachments/` | data | images pasted into prompts |
+| `profiles/<name>/` | config | `package.json` (bundle list and deps), `cordis.yml`, `cordis.patch.yml`, a pnpm lockfile, `node_modules` |
+| `sessions/<bucket>/<id>/` | data | the transcript (`session.v3.jsonl.zstd`) and a lock; the bucket name encodes the launch directory |
+| `AGENTS.md` | config | injected into the agent's instructions |
+
+## Home state versus profile state
+
+Credentials, settings, themes, history, the stash, storages, and sessions belong
+to the **home**: every profile in it shares them. The bundle list and the patch
+overlay belong to the **profile**: a new profile name starts from the base plus
+whatever is added to it, and inherits none of another profile's bundles or
+patches. That is the trap behind "test it in a profile named after the feature" —
+the run is compositionally thinner than the developer's own while still writing
+their real state.
+
+## What the dogfood clone changes
+
+The checkout package name selects its bundle in `profiles/<name>/package.json`.
+The generic helper adds it once if absent, repoints only its dependency, and
+rebuilds cloned local symlinks. It uses `dsh plugin add` only if the profile is
+missing after `dsh --help`, and does not modify the lockfile of an existing
+profile. Other bundles and the profile patch remain copied from the source home.
+One module, `scripts/clone-links.mjs`, holds the clone's link policy, so the
+seeding step and the validator read the same rules.
+
+`sessions/` is the only entry left out by default: it is the bulk of a home
+(190M of 200M in a busy one) and a test drive rarely needs it. `--with-sessions`
+copies it when present, which makes `--resume` reach the developer's history.
+
+## Failure modes worth knowing
+
+- **A missing row is silent.** `dsh plugin install` drops a bundle whose path
+  does not resolve and still exits 0; the profile then composes the base alone and
+  the surface waits with no output. Check
+  `node -p "require('<home>/profiles/<name>/package.json').dsh.profile.bundles"`.
+- **Mutable home state must remain inside the clone.** External symlinks in
+  settings, storages, or sessions and multiply linked mutable files stop the run.
+  Package links in `profiles/node_modules`, `profiles/*/node_modules`, and
+  `profiles/*/.dsh-module-fallback/node_modules` can point to global installs or
+  external checkouts, but not into the source home. An instruction file linked
+  into a shared prompt tree (`AGENTS.md`, `CLAUDE.md`) is read only and is copied
+  in while seeding, so the clone stays self-contained; a link to state the run may
+  write still stops the run. Writes through permitted package links are not
+  isolated. Re-seed with `--reseed` when the source changes.
+- **The clone keeps a copy of the credentials.** Create it in a scratch
+  directory, keep it `700`, and `--clean` it when done.
+- **The launcher decides the harness, not the profile.** `pnpm dsh` runs the
+  workspace-linked harness checkout (a dev build, which may fail to compose);
+  `dsh` on `PATH` is the released one. A profile cannot tell them apart.
+- **A turn can fail for reasons outside the surface** — no provider credit, a
+  sandbox policy, a missing credential. Read the error line in the transcript
+  before treating it as a rendering bug.
+
+## Cleanup
+
+```sh
+~/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh --status      # which clone, which target
+~/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh --clean       # removes it (marker-guarded)
+```
+
+The default clone lives at `${TMPDIR:-/tmp}/dsh-dogfood/<worktree>-<checkout-id>`
+and survives until `--clean` removes it. Cleanup validates the scratch-home
+marker against its canonical home, source, checkout, and profile.

package/.agents/skills/dsh-tui-dogfood/scripts/clone-links.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Link policy for the dogfood clone.
+ *
+ * A cloned home is a sandbox: a dogfood run may write only inside it. Two kinds
+ * of link are legitimate there — a package entry that resolves to an installed
+ * package or another checkout, and a link that stays inside the clone. A link
+ * that escapes is either copied in or refused, and which one depends on who
+ * writes the entry: the instruction files below are only read, so the bytes come
+ * along; everything else (credentials, settings, storages, sessions, profiles)
+ * is state the run may write, and a link out of the clone would let that write
+ * reach the developer's own home. Refusing is the safe answer there.
+ *
+ * Usage: clone-links.mjs check|materialize <home> <source>
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * Entries the surface only reads. A developer commonly links AGENTS.md into a
+ * shared tree, and refusing that would stop an otherwise safe run, so the copy
+ * is made instead. Nothing here may be added that any component writes.
+ */
+export const INSTRUCTION_ENTRIES = new Set(['AGENTS.md', 'CLAUDE.md'])
+
+/**
+ * Paths whose whole purpose is to point at an installed package, which may live
+ * outside the clone. A link here is expected; a link anywhere else is not.
+ */
+export const packageEntry = (parts) => parts[0] === 'profiles' && (
+  parts[1] === 'node_modules' && parts.length > 2 ||
+  parts[2] === 'node_modules' && parts.length > 3 ||
+  parts[2] === '.dsh-module-fallback' && parts[3] === 'node_modules' && parts.length > 4
+)
+
+export const inside = (root, file) => file === root || file.startsWith(root + path.sep)
+
+const instruction = (home, file) => {
+  const parts = path.relative(home, file).split(path.sep)
+  return parts.length === 1 && INSTRUCTION_ENTRIES.has(parts[0])
+}
+
+/**
+ * Absolute path a link target will occupy once it exists. A clone may hold a
+ * link to a file an install has not created yet, and the missing leaf can still
+ * sit under a link that crosses the clone boundary.
+ */
+export function destination(file) {
+  let ancestor = file
+  while (!fs.existsSync(ancestor)) {
+    const parent = path.dirname(ancestor)
+    if (parent === ancestor) throw Error('cannot resolve cloned link: ' + file)
+    ancestor = parent
+  }
+  return path.resolve(fs.realpathSync(ancestor), path.relative(ancestor, file))
+}
+
+const entries = (root) => fs.readdirSync(root, { withFileTypes: true })
+const partsOf = (home, file) => path.relative(home, file).split(path.sep)
+
+/** Every reason the clone cannot be run as a sandbox, in the order they are met. */
+export function problems(home, source) {
+  const found = []
+  const visit = (dir) => {
+    for (const entry of entries(dir)) {
+      const file = path.join(dir, entry.name)
+      const parts = partsOf(home, file)
+      if (entry.isSymbolicLink()) {
+        const target = destination(path.resolve(dir, fs.readlinkSync(file)))
+        const allowed = packageEntry(parts) ? !inside(source, target) : inside(home, target)
+        if (!allowed) found.push('unsafe cloned symlink escaping scratch or entering source home: ' + file)
+      } else if (entry.isDirectory()) {
+        visit(file)
+      } else if (entry.isFile() && !packageEntry(parts) && fs.lstatSync(file).nlink > 1) {
+        found.push('unsafe cloned hardlink outside package modules: ' + file)
+      }
+    }
+  }
+  visit(home)
+  return found
+}
+
+/** Copy every escaping instruction link in, so the clone can read it as its own. */
+export function materialize(home) {
+  const report = { copied: 0, dropped: 0 }
+  const visit = (dir) => {
+    for (const entry of entries(dir)) {
+      const file = path.join(dir, entry.name)
+      if (entry.isSymbolicLink()) {
+        const parts = partsOf(home, file)
+        if (packageEntry(parts) || !instruction(home, file)) continue
+        const target = destination(path.resolve(dir, fs.readlinkSync(file)))
+        if (inside(home, target)) continue
+        if (!fs.existsSync(target)) {
+          fs.rmSync(file)
+          console.log('materialize: dropped dangling link ' + path.relative(home, file))
+          report.dropped += 1
+          continue
+        }
+        const stat = fs.statSync(target)
+        fs.rmSync(file, { recursive: true, force: true })
+        if (stat.isDirectory()) {
+          fs.cpSync(target, file, { recursive: true, dereference: true })
+        } else {
+          fs.copyFileSync(target, file)
+          fs.chmodSync(file, stat.mode & 0o777)
+        }
+        console.log('materialize: copied ' + path.relative(home, file))
+        report.copied += 1
+        continue
+      }
+      if (entry.isDirectory()) visit(file)
+    }
+  }
+  visit(home)
+  return report
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const [mode, home, source] = process.argv.slice(2)
+  if (mode === 'check') {
+    const found = problems(home, source)
+    for (const problem of found) console.error(problem)
+    process.exitCode = found.length ? 1 : 0
+  } else if (mode === 'materialize') {
+    const report = materialize(home)
+    console.log('materialize: ' + report.copied + ' instruction link(s) copied, ' + report.dropped + ' dangling link(s) dropped')
+  } else {
+    console.error('usage: clone-links.mjs check|materialize <home> <source>')
+    process.exitCode = 2
+  }
+}