devs-common 4.0.4__tar.gz → 5.0.0__tar.gz

{devs_common-4.0.4 → devs_common-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devs-common
-Version: 4.0.4
+Version: 5.0.0
 Summary: Shared utilities for devs package ecosystem
 Author: Dan Lester
 License-Expression: MIT

{devs_common-4.0.4 → devs_common-5.0.0}/devs_common/core/container.py

@@ -332,6 +332,7 @@ class ContainerManager:
                     # Container exists but not running with matching config, just restart it
                     console.print(f"   🔄 Restarting stopped container...")
                     self.docker.start_container(existing_container['name'])
+                    self._run_post_start(existing_container['name'])
                     console.print(f"   ✅ Container restarted successfully")
                     return True
             else:
@@ -422,6 +423,50 @@ class ContainerManager:
             
             raise ContainerError(f"Failed to ensure container running for {dev_name}: {e}")
     
+    def _run_post_start(self, container_name: str) -> None:
+        """Run the container's postStart hook after a raw Docker start.
+
+        ``postStartCommand`` is a devcontainer-CLI concept: it fires on ``devcontainer
+        up`` and on a Dev Containers attach, but a plain ``docker start`` (which is how
+        we resume an already-built container) runs only PID 1 and skips it entirely.
+        Without this the hook's whole point is lost on the commonest restart path —
+        tailscaled and the tailnet node stay down, and VS Code settings aren't
+        re-deployed. The script is idempotent, so running it again is harmless. Never
+        raises: a container without the devs template simply has no such script.
+        """
+        try:
+            self.docker.exec_command(container_name, "/usr/local/bin/post-start.sh")
+        except Exception:
+            pass  # not a devs-template container / exec unavailable
+
+    def _deregister_tailnet_node(self, container_name: str, container_id: str) -> None:
+        """Best-effort tailnet cleanup when a container is destroyed (not just stopped).
+
+        Ephemeral Tailscale nodes auto-reap when the container stops, but that lags a
+        few minutes — long enough that an immediate recreate gets a clash-suffixed name
+        (…-eamonn-1). A graceful ``tailscale logout`` while the container is STILL UP
+        deregisters the node now, freeing the name for reuse. Then prune the writeback
+        handshake file start-tailscale.sh left in the env mount (nothing else reaps it;
+        the ``devs vscode`` resolver only reads files for containers that still exist, so
+        a missed prune is self-correcting). Never raises — teardown must not be blocked
+        by tailnet cleanup, and non-tailnet containers simply no-op here.
+        """
+        # 1. Graceful logout while the daemon is still alive (frees the tailnet name now).
+        try:
+            self.docker.exec_command(container_name, "sudo -n /usr/local/bin/ts-cli.sh logout")
+        except Exception:
+            pass  # no tailscale in this container / daemon down / exec unavailable
+
+        # 2. Prune the handshake file (keyed by the container's short id == its hostname).
+        try:
+            nodes_dir = get_env_mount_path(self.project.info.name) / "ts-nodes"
+            if nodes_dir.is_dir():
+                for handshake in nodes_dir.glob("*.json"):
+                    if container_id and container_id.startswith(handshake.stem):
+                        handshake.unlink()
+        except Exception:
+            pass
+
     def stop_container(self, dev_name: str, remove: bool = True) -> bool:
         """Stop a container by labels, optionally removing it.
 
@@ -442,6 +487,11 @@ class ContainerManager:
                 for container_info in existing_containers:
                     container_name = container_info['name']
 
+                    if remove:
+                        # Free the tailnet node + handshake BEFORE stopping — logout
+                        # needs the container's tailscaled still running.
+                        self._deregister_tailnet_node(container_name, container_info.get('id', ''))
+
                     try:
                         self.docker.stop_container(container_name)
                     except DockerError as stop_e:
@@ -600,7 +650,10 @@ class ContainerManager:
         for container in containers:
             try:
                 console.print(f"   🗑️  Removing aborted container: {container.name} ({container.status})")
-                
+
+                # Best-effort tailnet cleanup (logout if still up + prune handshake file).
+                self._deregister_tailnet_node(container.name, container.container_id or '')
+
                 # Stop container first if it's running
                 if container.status.lower() in ['running', 'restarting']:
                     console.print(f"   🛑 Stopping running container: {container.name}")
@@ -664,6 +717,7 @@ class ContainerManager:
                 container_id = existing_containers[0].get('name', container_name)
                 console.print(f"   ▶️  Starting stopped container: {container_id}")
                 self.docker.start_container(container_id)
+                self._run_post_start(container_id)
         else:
             # Ensure container is running (may create/restart as needed, but never auto-rebuild)
             if not self.ensure_container_running(dev_name, workspace_dir, check_rebuild=False, debug=debug, live=live, extra_env=extra_env):

{devs_common-4.0.4 → devs_common-5.0.0}/devs_common/templates/Dockerfile

@@ -35,6 +35,7 @@ RUN apt update && apt install -y less \
   vim \
   nano \
   htop \
+  tmux \
   && apt clean \
   && rm -rf /var/lib/apt/lists/*
 
@@ -87,11 +88,33 @@ RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhisto
 ENV DEVCONTAINER=true
 
 # Create workspace and config directories and set permissions
-RUN mkdir -p /workspaces /home/node/claudeconfig /home/node/codexconfig /home/node/.vscode-server/extensions && \
+RUN mkdir -p /workspaces /home/node/claudeconfig /home/node/codexconfig \
+      /home/node/.vscode-server/extensions \
+      /home/node/.vscode-server/data/Machine && \
   echo '[]' > /home/node/.vscode-server/extensions/extensions.json && \
   chown -R node:node /workspaces /home/node /home/node/.vscode-server && \
   chmod 755 /workspaces
 
+# Pre-install workspace-kind VS Code extensions so they're available on first connect.
+# devcontainer.json's extensions list is only auto-installed by the Dev Containers
+# extension; over an SSH remote it's silently skipped.
+RUN for EXT in vscode-tmux-auto-reattach devs-bridge-drop; do \
+      curl -fSL --retry 3 --compressed \
+        "https://marketplace.visualstudio.com/_apis/public/gallery/publishers/ideonate/vsextensions/${EXT}/latest/vspackage" \
+        -o /tmp/ext.vsix && \
+      unzip -q /tmp/ext.vsix "extension/package.json" -d /tmp/ext-meta && \
+      VERSION=$(node -e "console.log(require('/tmp/ext-meta/extension/package.json').version)") && \
+      EXT_DIR="/home/node/.vscode-server/extensions/ideonate.${EXT}-${VERSION}" && \
+      mkdir -p "${EXT_DIR}" && \
+      unzip -q /tmp/ext.vsix "extension/*" -d /tmp/ext && \
+      cp -r /tmp/ext/extension/. "${EXT_DIR}/" && \
+      rm -rf /tmp/ext.vsix /tmp/ext /tmp/ext-meta; \
+    done && \
+    chown -R node:node /home/node/.vscode-server/extensions/
+COPY register-vscode-extensions.js /tmp/
+RUN node /tmp/register-vscode-extensions.js && rm /tmp/register-vscode-extensions.js && \
+    chown node:node /home/node/.vscode-server/extensions/extensions.json
+
 WORKDIR /workspaces
 
 # Install git-delta for better git diffs
@@ -143,6 +166,18 @@ RUN ARCH=$(dpkg --print-architecture) && \
   rm /tmp/vscode-cli.tar.gz && \
   chmod +x /usr/local/bin/code
 
+# Install Tailscale (static binaries) so each devcontainer can join the tailnet
+# as its own node in userspace-networking mode — see scripts/start-tailscale.sh.
+# Pinned for reproducible builds; bump as needed.
+ARG TAILSCALE_VERSION=1.98.4
+RUN ARCH=$(dpkg --print-architecture) && \
+  curl -fSL --retry 5 --retry-delay 5 --retry-all-errors --connect-timeout 30 \
+    "https://pkgs.tailscale.com/stable/tailscale_${TAILSCALE_VERSION}_${ARCH}.tgz" -o /tmp/tailscale.tgz && \
+  tar -xzf /tmp/tailscale.tgz -C /tmp && \
+  mv "/tmp/tailscale_${TAILSCALE_VERSION}_${ARCH}/tailscale" "/tmp/tailscale_${TAILSCALE_VERSION}_${ARCH}/tailscaled" /usr/local/bin/ && \
+  rm -rf /tmp/tailscale.tgz "/tmp/tailscale_${TAILSCALE_VERSION}_${ARCH}" && \
+  chmod +x /usr/local/bin/tailscale /usr/local/bin/tailscaled
+
 # Set up environment variables and aliases for Claude and Codex
 RUN for shell_rc in /home/node/.zshrc /home/node/.bashrc; do \
   echo "export CLAUDE_CONFIG_DIR=\"/home/node/claudeconfig\"" >> "$shell_rc" && \
@@ -159,11 +194,33 @@ RUN for shell_rc in /home/node/.zshrc /home/node/.bashrc; do \
   echo "export TEST_RESULTS_FOLDER=\"/home/node/bridge/test-results\"" >> "$shell_rc"; \
   done
 
+# tmux defaults: mouse scrolling, deep scrollback, and live tab titles. Pairs with the
+# ideonate.vscode-tmux-auto-reattach extension (liveTitles mode). Present regardless of
+# DEVS_TMUX — this only shapes tmux when you actually run it.
+RUN printf '%s\n' \
+  'set -g mouse on' \
+  'set -g history-limit 50000' \
+  'bind m set -g mouse \; display "mouse #{?mouse,on,off}"' \
+  'set -g set-titles on' \
+  "set -g set-titles-string '#{session_name}: #{pane_current_command}'" \
+  > /home/node/.tmux.conf && \
+  chown node:node /home/node/.tmux.conf
+
+# VS Code settings live here rather than in devcontainer.json's
+# customizations.vscode.settings, because that block is only applied by the Dev
+# Containers extension — a Remote-SSH connection (e.g. over Tailscale SSH) never reads
+# devcontainer.json. Baking them as machine settings covers both paths. Both files also
+# land in /etc/devcontainer-config/ so scripts/setup-vscode-settings.sh can re-deploy
+# them at container start with the optional tmux overlay (DEVS_TMUX=1) applied.
+# See templates/README-vscode-settings.md.
+COPY --chown=node:node machine-settings.json /home/node/.vscode-server/data/Machine/settings.json
+COPY machine-settings.json machine-settings.tmux.json /etc/devcontainer-config/
 
 # Copy and set up scripts
 COPY scripts/ /usr/local/bin/
 COPY sudo-scripts/ /usr/local/bin/
-RUN chmod +x /usr/local/bin/*.sh /usr/local/bin/*.py
+RUN chmod +x /usr/local/bin/*.sh /usr/local/bin/*.py && \
+  ln -sf /usr/local/bin/ts.sh /usr/local/bin/ts
 COPY sudo-scripts/ /tmp/sudo-scripts-list/
 RUN echo "DEBUG: Files that need sudo:" && ls -la /tmp/sudo-scripts-list/ && \
   { echo "# Allow node user to run sudo scripts without password"; \

devs_common-5.0.0/devs_common/templates/README-vscode-settings.md

@@ -0,0 +1,44 @@
+# VS Code settings in this template
+
+`machine-settings.json` is baked into the image at
+`~/.vscode-server/data/Machine/settings.json` (see the Dockerfile), **not** put in
+`devcontainer.json` under `customizations.vscode.settings`.
+
+Why: that `customizations` block is applied by the **Dev Containers extension only**. A
+Remote-SSH connection — which is how you reach a container over Tailscale SSH — never reads
+`devcontainer.json`, so it got neither settings nor extensions. Machine settings cover both
+paths. For the same reason the `ideonate.*` extensions are unzipped into the image and
+registered via `register-vscode-extensions.js`.
+
+**Don't add a `settings` block back to `devcontainer.json`**: the Dev Containers extension
+writes it over the same machine-settings file, and the two would silently drift.
+
+## tmux (opt-in, off by default)
+
+`machine-settings.json` *defines* a `tmux` terminal profile and the
+`ideonate.vscode-tmux-auto-reattach` settings, but leaves the default profile as `zsh` and
+`tmuxAutoReattach.runOnStartup` as `false`. Nothing changes unless you ask for it.
+
+To turn it on, set `DEVS_TMUX=1` — via `DEVS.yml` `env_vars:`, `devs start … --env
+DEVS_TMUX=1`, or a mounted `~/.devs/envs/<project>/.env`. On each container start,
+`scripts/setup-vscode-settings.sh` merges `machine-settings.tmux.json` over the base file,
+which flips the default profile to tmux and enables auto-reattach. Unset it and the next
+start reverts to the base file — no rebuild needed either way.
+
+You can still open a tmux terminal manually from the profile dropdown with `DEVS_TMUX`
+unset; the profile is always defined.
+
+### Notes on the tmux settings
+
+- `~/.tmux.conf` (written in the Dockerfile) sets `mouse on`, 50k scrollback, and
+  `set-titles` so tab titles show the running command. Existing sessions keep their old
+  config — `tmux source-file ~/.tmux.conf` then start a new session, or `tmux kill-server`.
+- With `mouse on`, click-drag and double-click go to tmux rather than VS Code.
+  `terminal.integrated.macOptionClickForcesSelection` (on in the base file) lets
+  Option-click/drag bypass tmux for native selection. `prefix + m` toggles mouse mode.
+- `tmuxAutoReattach.shellPath=/bin/sh` runs the reattach as the terminal's own process.
+  Without it the terminal starts the default profile (`tmux new-session`) first and the
+  attach nests inside that tmux.
+- `terminal.integrated.enablePersistentSessions: false` (tmux overlay) stops VS Code
+  reviving old terminal tabs on reload — each would launch the default profile before the
+  extension can reattach, again causing nested tmux.

{devs_common-4.0.4 → devs_common-5.0.0}/devs_common/templates/devcontainer.json

@@ -22,55 +22,14 @@
         "ms-python.black-formatter",
         "ms-python.isort",
         "Anthropic.claude-code",
-        "ideonate.devs-bridge-drop"
-      ],
-      "settings": {
-        "editor.formatOnSave": false,
-        "editor.defaultFormatter": "esbenp.prettier-vscode",
-        "editor.codeActionsOnSave": {
-          "source.fixAll.eslint": "explicit"
-        },
-        "editor.detectIndentation": false,
-        "editor.insertSpaces": true,
-        "editor.tabSize": 2,
-        "[python]": {
-          "editor.formatOnSave": true,
-          "editor.formatOnType": true,
-          "editor.tabSize": 4,
-          "editor.codeActionsOnSave": {
-            "source.organizeImports": "never"
-          }
-        },
-        "python.defaultInterpreterPath": "/home/node/.devs-venv/workspace-venv/bin/python",
-        "python.terminal.activateEnvironment": true,
-        "python.interpreter.infoVisibility": "never",
-        "python.venvFolders": [".devs-venv"],
-        "python.languageServer": "Pylance",
-        "python.analysis.typeCheckingMode": "off",
-        "python.analysis.autoImportCompletions": true,
-        "python.analysis.diagnosticSeverityOverrides": {
-          "reportUnusedImport": "information",
-          "reportUnusedVariable": "information"
-        },
-        "pylint.enabled": false,
-        "gitlens.mode": "zen",
-        "python.analysis.diagnosticMode": "openFilesOnly",
-        "settingsSync.ignoredExtensions": [],
-        "settingsSync.keybindingsPerPlatform": false,
-        "extensions.autoCheckUpdates": false,
-        "extensions.autoUpdate": false,
-        "extensions.ignoreRecommendations": true,
-        "terminal.integrated.defaultProfile.linux": "zsh",
-        "terminal.integrated.profiles.linux": {
-          "bash": {
-            "path": "bash",
-            "icon": "terminal-bash"
-          },
-          "zsh": {
-            "path": "zsh"
-          }
-        }
-      }
+        "ideonate.devs-bridge-drop",
+        "ideonate.vscode-tmux-auto-reattach"
+      ]
+      // VS Code settings live in .devcontainer/machine-settings.json — baked into
+      // the image via Dockerfile so they apply for both Dev Containers and SSH
+      // remote (Tailscale SSH never reads devcontainer.json). Don't add a
+      // "settings" block back here: the Dev Containers extension writes it over
+      // the same machine-settings file, and the two would drift.
     }
   },
   "remoteUser": "node",
@@ -84,7 +43,11 @@
     // "source=${localEnv:WORKSPACE_FOLDER_NAME}-vscode-extensions,target=/home/node/.vscode-server/extensions,type=volume",
     // .vscode-server includes extension state which we don't want to keep
     // "source=${localEnv:WORKSPACE_FOLDER_NAME}-vscode-data,target=/home/node/.vscode-server,type=volume",
-    "source=${localEnv:WORKSPACE_FOLDER_NAME}-vscode-downloads,target=/home/node/.vscode-extensions-cache-volume,type=volume"
+    "source=${localEnv:WORKSPACE_FOLDER_NAME}-vscode-downloads,target=/home/node/.vscode-extensions-cache-volume,type=volume",
+    // Persist the tailnet node identity so the container keeps one stable 100.x
+    // and hostname across rebuilds — otherwise every rebuild mints a new node and
+    // your saved VS Code SSH host stops resolving.
+    "source=${localEnv:WORKSPACE_FOLDER_NAME}-tailscale-state,target=/var/lib/tailscale,type=volume"
   ],
   "remoteEnv": {
     "NODE_OPTIONS": "--max-old-space-size=4096",
@@ -93,13 +56,19 @@
     "LC_ALL": "en_US.UTF-8",
     "GIT_REMOTE_URL": "${localEnv:GIT_REMOTE_URL}",
     "WORKSPACE_FOLDER_NAME": "${localEnv:WORKSPACE_FOLDER_NAME}",
+    "DEVCONTAINER_NAME": "${localEnv:DEVCONTAINER_NAME}",
+    "DEVS_PROJECT_NAME": "${localEnv:DEVS_PROJECT_NAME}",
     "DEVS_DEBUG": "${localEnv:DEVS_DEBUG}",
     "DEVS_LIVE_MODE": "${localEnv:DEVS_LIVE_MODE}",
+    // Opt-in: makes tmux the default terminal profile and enables auto-reattach.
+    // Off unless set to 1/true/yes — see scripts/setup-vscode-settings.sh.
+    "DEVS_TMUX": "${localEnv:DEVS_TMUX}",
     "DEVS_ENV_MOUNT_PATH": "${localEnv:DEVS_ENV_MOUNT_PATH}",
     "DEVS_BRIDGE_MOUNT_PATH": "${localEnv:DEVS_BRIDGE_MOUNT_PATH}"
   },
   "workspaceFolder": "/workspaces/${localEnv:WORKSPACE_FOLDER_NAME}",
   "postCreateCommand": "/usr/local/bin/post-create-wrapper.sh",
+  "postStartCommand": "/usr/local/bin/post-start.sh",
   "forwardPorts": [],
   "portsAttributes": {
     "3306": {

devs_common-5.0.0/devs_common/templates/machine-settings.json

@@ -0,0 +1,61 @@
+{
+  "editor.formatOnSave": false,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "editor.detectIndentation": false,
+  "editor.insertSpaces": true,
+  "editor.tabSize": 2,
+  "[python]": {
+    "editor.formatOnSave": true,
+    "editor.formatOnType": true,
+    "editor.tabSize": 4,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": "never"
+    }
+  },
+  "python.defaultInterpreterPath": "/home/node/.devs-venv/workspace-venv/bin/python",
+  "python.terminal.activateEnvironment": true,
+  "python.interpreter.infoVisibility": "never",
+  "python.venvFolders": [".devs-venv"],
+  "python.languageServer": "Pylance",
+  "python.analysis.typeCheckingMode": "off",
+  "python.analysis.autoImportCompletions": true,
+  "python.analysis.diagnosticSeverityOverrides": {
+    "reportUnusedImport": "information",
+    "reportUnusedVariable": "information"
+  },
+  "pylint.enabled": false,
+  "gitlens.mode": "zen",
+  "python.analysis.diagnosticMode": "openFilesOnly",
+  "settingsSync.ignoredExtensions": [],
+  "settingsSync.keybindingsPerPlatform": false,
+  "extensions.autoCheckUpdates": false,
+  "extensions.autoUpdate": false,
+  "extensions.ignoreRecommendations": true,
+  "terminal.integrated.defaultProfile.linux": "zsh",
+  "terminal.integrated.profiles.linux": {
+    "bash": {
+      "path": "bash",
+      "icon": "terminal-bash"
+    },
+    "zsh": {
+      "path": "zsh"
+    },
+    "tmux": {
+      "path": "tmux",
+      "args": ["new-session", "-A", "-s", "main"],
+      "icon": "terminal-tmux"
+    }
+  },
+  "terminal.integrated.macOptionClickForcesSelection": true,
+  "tmuxAutoReattach.runOnStartup": false,
+  "tmuxAutoReattach.skipIfTerminalsOpen": true,
+  "tmuxAutoReattach.listCommand": "tmux list-sessions -F \"#{session_name}\"",
+  "tmuxAutoReattach.attachCommand": "tmux attach -t {session}",
+  "tmuxAutoReattach.shellPath": "/bin/sh",
+  "tmuxAutoReattach.shellArgs": ["-c"],
+  "tmuxAutoReattach.liveTitles": true,
+  "tmuxAutoReattach.titleCommand": ""
+}

devs_common-5.0.0/devs_common/templates/machine-settings.tmux.json

@@ -0,0 +1,6 @@
+{
+  "terminal.integrated.defaultProfile.linux": "tmux",
+  "tmuxAutoReattach.runOnStartup": true,
+  "terminal.integrated.tabs.title": "${sequence}",
+  "terminal.integrated.enablePersistentSessions": false
+}

devs_common-5.0.0/devs_common/templates/register-vscode-extensions.js

@@ -0,0 +1,33 @@
+// Writes extensions.json so VS Code SSH remote discovers pre-installed extensions.
+// VS Code trusts this registry rather than scanning the directory.
+const fs = require("fs");
+const path = require("path");
+
+const extDir = "/home/node/.vscode-server/extensions";
+
+const entries = fs
+  .readdirSync(extDir)
+  .filter(
+    (d) =>
+      !d.endsWith(".json") && fs.statSync(path.join(extDir, d)).isDirectory(),
+  )
+  .flatMap((dir) => {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(extDir, dir, "package.json"), "utf8"),
+      );
+      return [
+        {
+          identifier: { id: `${pkg.publisher}.${pkg.name}` },
+          version: pkg.version,
+          location: { $mid: 1, path: path.join(extDir, dir), scheme: "file" },
+          relativeLocation: dir,
+          metadata: { installedTimestamp: 1700000000000, source: "vsix" },
+        },
+      ];
+    } catch (e) {
+      return [];
+    }
+  });
+
+fs.writeFileSync(path.join(extDir, "extensions.json"), JSON.stringify(entries));

{devs_common-4.0.4 → devs_common-5.0.0}/devs_common/templates/scripts/post-create-wrapper.sh

@@ -37,6 +37,8 @@ run_step "setup-devs-env.sh" "/usr/local/bin/setup-devs-env.sh"
 #run_step "init-firewall.sh" "sudo /usr/local/bin/init-firewall.sh"
 run_step "setup-workspace.sh" "/usr/local/bin/setup-workspace.sh"
 run_step "start-services.sh" "sudo /usr/local/bin/start-services.sh"
+# Optional: join the tailnet + serve a port. Non-fatal — no auth key => no-op.
+run_step "start-tailscale.sh" "/usr/local/bin/start-tailscale.sh" || true
 
 # GitHub auth setup is optional, so handle it separately
 echo "📋 Running gh auth setup-git..."

devs_common-5.0.0/devs_common/templates/scripts/post-start.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# postStartCommand orchestrator (runs as the node user on every container start).
+# Unprivileged: env/gating logic, then hands privileged work to root sudo-scripts.
+#
+# Why this runs on EVERY start (not just postCreate): a plain container restart
+# (host reboot, `docker start`) re-runs only PID 1, not the devcontainer
+# create-lifecycle. So tailscaled, the tailnet node and Tailscale SSH are all gone
+# after a restart — and a VS Code Remote-SSH connection to that node then has
+# nothing to reconnect to. Re-running the bring-up here restores it automatically.
+# Every step is idempotent, so running it again right after postCreate (on first
+# create) is a harmless no-op.
+set -uo pipefail
+
+# Same env source start-tailscale.sh reads TS_ENABLE/TS_AUTHKEY from.
+if [ -f /home/node/.devs-env/.env ]; then
+  set -a; . /home/node/.devs-env/.env; set +a
+fi
+
+# VS Code machine settings (+ optional tmux overlay, off unless DEVS_TMUX=1). Not
+# Tailscale-gated — it configures the editor regardless of how you connect. Must come
+# before the TS_ENABLE gate below, which exits when Tailscale is off.
+/usr/local/bin/setup-vscode-settings.sh || true
+
+# Gate on the same master switch as the rest of the Tailscale wiring.
+case "${TS_ENABLE:-}" in
+  1|true|yes) ;;
+  *)
+    echo "ℹ️  Tailscale not enabled (TS_ENABLE=${TS_ENABLE:-unset}) — skipping tailnet setup."
+    exit 0 ;;
+esac
+
+# Re-join the tailnet (idempotent): ensures tailscaled is running — self-healing a
+# stale socket left by the previous boot, see sudo-scripts/start-tailscaled.sh —
+# then re-runs `tailscale up` (+ serve/funnel). The hostname derives from the same
+# remoteEnv (DEVS_PROJECT_NAME/DEVCONTAINER_NAME) the create path uses, and the
+# persisted /var/lib/tailscale state reclaims the same identity, so the node's
+# name stays stable across restarts and rebuilds.
+/usr/local/bin/start-tailscale.sh || true
+
+# Prepend the MagicDNS resolver so tailnet split-DNS names resolve from inside the
+# container. Must run after the bring-up above (it no-ops unless tailscaled is up),
+# and on every start because Docker regenerates /etc/resolv.conf each time.
+sudo -n /usr/local/bin/setup-magicdns.sh || true

devs_common-5.0.0/devs_common/templates/scripts/setup-vscode-settings.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Deploy VS Code machine settings, applying the optional tmux overlay.
+#
+# Settings live in ~/.vscode-server/data/Machine/settings.json rather than in
+# devcontainer.json's customizations.vscode.settings, because that block is applied by
+# the Dev Containers extension only — a Remote-SSH connection (e.g. over Tailscale SSH)
+# never reads devcontainer.json. See templates/README-vscode-settings.md.
+#
+# The Dockerfile already bakes the base file, so a container is correctly configured even
+# if this never runs. This script exists for the DEVS_TMUX toggle: it re-deploys the base
+# and merges machine-settings.tmux.json over it when tmux is requested, so switching is a
+# container restart rather than an image rebuild.
+#
+#   DEVS_TMUX   "1"/"true"/"yes" => tmux becomes the default terminal profile and
+#               ideonate.vscode-tmux-auto-reattach reattaches sessions on window load.
+#               OFF by default: the tmux profile is defined either way, so you can pick
+#               it from the terminal dropdown without opting in globally.
+set -uo pipefail
+
+BASE=/etc/devcontainer-config/machine-settings.json
+OVERLAY=/etc/devcontainer-config/machine-settings.tmux.json
+DEST=/home/node/.vscode-server/data/Machine/settings.json
+
+[ -f "$BASE" ] || exit 0
+
+# Same env source the other devs container scripts read their switches from.
+if [ -f /home/node/.devs-env/.env ]; then
+  set -a; . /home/node/.devs-env/.env; set +a
+fi
+
+mkdir -p "$(dirname "$DEST")"
+
+case "${DEVS_TMUX:-}" in
+  1|true|yes)
+    if [ -f "$OVERLAY" ] && node -e '
+      const fs = require("fs");
+      const [base, overlay, dest] = process.argv.slice(1);
+      const merged = {
+        ...JSON.parse(fs.readFileSync(base, "utf8")),
+        ...JSON.parse(fs.readFileSync(overlay, "utf8")),
+      };
+      fs.writeFileSync(dest, JSON.stringify(merged, null, 2) + "\n");
+    ' "$BASE" "$OVERLAY" "$DEST"; then
+      echo "🖥️  VS Code settings deployed (tmux enabled — DEVS_TMUX=${DEVS_TMUX})."
+    else
+      cp "$BASE" "$DEST"
+      echo "⚠️  tmux overlay merge failed — deployed base VS Code settings instead."
+    fi
+    ;;
+  *)
+    cp "$BASE" "$DEST"
+    echo "🖥️  VS Code settings deployed (tmux off; set DEVS_TMUX=1 to enable)."
+    ;;
+esac

devs_common-5.0.0/devs_common/templates/scripts/start-tailscale.sh

@@ -0,0 +1,158 @@
+#!/bin/bash
+# Join this devcontainer to the user's tailnet as its own node, and optionally
+# publish a port over HTTPS (serve/funnel) and/or accept Tailscale SSH. Invoked (as
+# the node user) from post-create-wrapper.sh and post-start.sh — the latter so the
+# node comes back after a restart. Safe no-op unless TS_ENABLE=1.
+#
+# This orchestrator runs unprivileged and does the env/gating/hostname logic; the
+# privileged bits go through root sudo-scripts (start-tailscaled.sh / ts-cli.sh),
+# matching the init-firewall pattern. tailscaled runs as root in userspace
+# networking mode — no TUN device needed, and root is what lets Tailscale SSH open
+# login sessions.
+#
+# Config — all via env. The natural place to set these is the per-project env
+# file ~/.devs/envs/<project>/.env on the host, which devs mounts at
+# /home/node/.devs-env/.env and which this script sources below:
+#   TS_ENABLE      master switch, STRICTLY OPT-IN. Off unless set to
+#                  "1"/"true"/"yes". A key alone does NOT enable Tailscale, so an
+#                  auth key can live in the shared default .env harmlessly until a
+#                  given project sets TS_ENABLE=1.
+#   TS_AUTHKEY     PREFERRED key: a reusable, tagged, NON-ephemeral key from the
+#                  Tailscale admin console. Non-ephemeral is deliberate — the node
+#                  survives going offline (WAN blip / host sleep) and just reconnects,
+#                  so you can rely on SSH-ing into it. (An *ephemeral* node is instead
+#                  garbage-collected by the control plane shortly after it disconnects;
+#                  if that happens while the container keeps running, tailscaled wedges
+#                  retrying a dead node key — "PollNetMap: initial fetch failed 404:
+#                  node not found" — until the next bring-up.)
+#   TS_AUTHKEY_EPHEMERAL
+#                  FALLBACK key, used only when TS_AUTHKEY is unset: a reusable,
+#                  tagged, EPHEMERAL key. Gives a throwaway node that auto-cleans when
+#                  the container goes away (no stale-node clutter), accepting the
+#                  mid-life-GC caveat above. Natural home: the shared default .env, so
+#                  any container still joins the tailnet even without a per-project
+#                  stable key. With NEITHER set (and TS_ENABLE=1) => warn + exit 0.
+#   TS_HOSTNAME    tailnet hostname. Default: <DEVS_PROJECT_NAME>-<DEVCONTAINER_NAME>
+#                  (e.g. myorg-myapp-alice) -> <name>.<tailnet>.ts.net.
+#                  Dev name alone isn't unique across projects, hence the prefix.
+#   TS_TAGS        advertised tags (default: tag:devcontainer). Must match the
+#                  tagOwners in your tailnet ACL and the auth key's tag.
+#   TS_SERVE_PORT  if set, serve this local port over HTTPS on the node's name.
+#   TS_FUNNEL      "1"/"true": expose TS_SERVE_PORT to the PUBLIC internet
+#                  (Funnel) instead of tailnet-only serve.
+#   TS_SSH         "1"/"true": accept Tailscale SSH into the container (needs an
+#                  `ssh` rule in the tailnet ACL allowing the `node` user).
+set -uo pipefail
+
+# Pull in secrets/config from the mounted devs env file, if present.
+if [ -f /home/node/.devs-env/.env ]; then
+  set -a; . /home/node/.devs-env/.env; set +a
+fi
+
+# Master switch — strictly opt-in, off by default (like the firewall). A key
+# alone does NOT enable it, so a tailnet auth key can sit in the shared default
+# .env harmlessly until a project explicitly sets TS_ENABLE=1.
+case "${TS_ENABLE:-}" in
+  1|true|yes) ;;
+  *)
+    echo "ℹ️  Tailscale not enabled (TS_ENABLE=${TS_ENABLE:-unset}) — skipping."
+    echo "    Set TS_ENABLE=1 (+ TS_AUTHKEY) to join the tailnet."
+    exit 0 ;;
+esac
+
+# Pick the auth key: prefer the stable (non-ephemeral) TS_AUTHKEY; fall back to an
+# ephemeral throwaway key. KEY_MODE is just for logging — the node's actual
+# ephemerality is baked into whichever key was minted, not set here.
+if [ -n "${TS_AUTHKEY:-}" ]; then
+  AUTHKEY="$TS_AUTHKEY"; KEY_MODE="stable (non-ephemeral)"
+elif [ -n "${TS_AUTHKEY_EPHEMERAL:-}" ]; then
+  AUTHKEY="$TS_AUTHKEY_EPHEMERAL"; KEY_MODE="ephemeral (fallback)"
+else
+  echo "⚠️  TS_ENABLE is set but no key found — skipping Tailscale."
+  echo "    Set TS_AUTHKEY (reusable, tagged, non-ephemeral) for a stable node,"
+  echo "    or TS_AUTHKEY_EPHEMERAL (reusable, tagged, ephemeral) for a throwaway one,"
+  echo "    in a mounted .env (e.g. ~/.devs/envs/default/.env)."
+  exit 0
+fi
+
+SSH_ON=""
+case "${TS_SSH:-}" in 1|true|yes) SSH_ON=1 ;; esac
+
+# tailscale CLI against the root daemon, via the NOPASSWD sudo-script.
+TS=(sudo -n /usr/local/bin/ts-cli.sh)
+
+# Derive a DNS-safe hostname. Prefer an explicit override; else <project>-<dev>
+# (unique across projects, stable in both live and copy modes); else fall back.
+if [ -n "${TS_HOSTNAME:-}" ]; then
+  RAW_NAME="$TS_HOSTNAME"
+elif [ -n "${DEVS_PROJECT_NAME:-}" ] && [ -n "${DEVCONTAINER_NAME:-}" ]; then
+  RAW_NAME="${DEVS_PROJECT_NAME}-${DEVCONTAINER_NAME}"
+else
+  RAW_NAME="${WORKSPACE_FOLDER_NAME:-${DEVCONTAINER_NAME:-devcontainer}}"
+fi
+HOSTNAME_TS=$(printf '%s' "$RAW_NAME" | tr '[:upper:]' '[:lower:]' | tr -cd '[:alnum:]-')
+HOSTNAME_TS="${HOSTNAME_TS:-devcontainer}"
+# Namespace every devs node under a single `devs-` prefix so one `Host devs-*`
+# block in ~/.ssh/config covers all repos with this devcontainer structure.
+# Idempotent: strip any existing prefix first so we never get `devs-devs-`.
+HOSTNAME_TS="devs-${HOSTNAME_TS#devs-}"
+TAGS="${TS_TAGS:-tag:devcontainer}"
+
+# Start the daemon (root, detached, idempotent) if not already up.
+echo "🔌 Ensuring tailscaled is running (userspace networking, root)…"
+sudo -n /usr/local/bin/start-tailscaled.sh
+
+up_args=(--authkey="$AUTHKEY" --hostname="$HOSTNAME_TS"
+         --advertise-tags="$TAGS" --accept-dns=false --accept-routes=false)
+[ -n "$SSH_ON" ] && up_args+=(--ssh)
+
+echo "🔗 tailscale up as '$HOSTNAME_TS' [$KEY_MODE] (tags: $TAGS${SSH_ON:+, ssh})…"
+if ! "${TS[@]}" up "${up_args[@]}"; then
+  echo "⚠️  tailscale up failed — see /var/log/tailscaled.log. Container continues without Tailscale."
+  exit 0
+fi
+
+dnsname=$("${TS[@]}" status --json 2>/dev/null | jq -r '.Self.DNSName // empty' | sed 's/\.$//')
+echo "✅ On tailnet as: ${dnsname:-$HOSTNAME_TS}"
+[ -n "$SSH_ON" ] && echo "🔑 Tailscale SSH on — connect with: ssh node@${dnsname:-$HOSTNAME_TS}"
+
+# Writeback handshake: record this node's resolved tailnet identity into the
+# host-shared env mount (a rw bind mount), keyed by our docker container id (the
+# container's $HOSTNAME, which `docker inspect --format '{{.Config.Hostname}}'`
+# returns on the host). Lets `devs vscode` join container -> tailnet node by
+# container id with a cheap `docker inspect` (no `docker exec`) and use the REAL
+# resolved name — immune to tailnet clash-suffixing (…-eamonn-1) and TS_HOSTNAME
+# overrides. Pruned by `devs clean`; stale files are simply never read.
+if [ -n "${dnsname:-}" ] && [ -d /home/node/.devs-env ]; then
+  cid="${HOSTNAME:-$(hostname 2>/dev/null)}"
+  ssh_flag=false; [ -n "$SSH_ON" ] && ssh_flag=true
+  nodes_dir=/home/node/.devs-env/ts-nodes
+  if mkdir -p "$nodes_dir" 2>/dev/null && \
+     jq -n --arg dnsname "$dnsname" --arg short "${dnsname%%.*}" \
+           --arg container_id "$cid" --arg dev "${DEVCONTAINER_NAME:-}" \
+           --argjson ssh "$ssh_flag" \
+       '{dnsname:$dnsname, short:$short, container_id:$container_id, dev:$dev, ssh:$ssh}' \
+       > "$nodes_dir/$cid.json" 2>/dev/null; then
+    echo "📝 Tailnet handshake → .devs-env/ts-nodes/$cid.json"
+  else
+    echo "⚠️  Could not write tailnet handshake file (continuing)."
+  fi
+fi
+
+# Optionally publish a port.
+if [ -n "${TS_SERVE_PORT:-}" ]; then
+  case "${TS_FUNNEL:-}" in
+    1|true|yes)
+      echo "🌐 funnel (PUBLIC internet) → :$TS_SERVE_PORT"
+      "${TS[@]}" funnel --bg "$TS_SERVE_PORT" \
+        || echo "⚠️  funnel failed (needs Funnel enabled + the funnel node attribute in ACL)"
+      ;;
+    *)
+      echo "🔒 serve (tailnet only) → :$TS_SERVE_PORT"
+      "${TS[@]}" serve --bg "$TS_SERVE_PORT" \
+        || echo "⚠️  serve failed (needs HTTPS certificates enabled on the tailnet)"
+      ;;
+  esac
+  "${TS[@]}" serve status 2>/dev/null || true
+fi
+exit 0

devs_common-5.0.0/devs_common/templates/scripts/ts.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Convenience wrapper: talk to this container's (root) tailscaled via the NOPASSWD
+# sudo-script. Symlinked to `ts` on PATH, e.g. `ts status`, `ts serve --bg 5173`.
+exec sudo -n /usr/local/bin/ts-cli.sh "$@"

devs_common-5.0.0/devs_common/templates/sudo-scripts/setup-magicdns.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Root helper (NOPASSWD sudo-script): make the container resolve the Tailscale
+# split-DNS sample-app hostnames by prepending the MagicDNS resolver
+# (100.100.100.100) to /etc/resolv.conf. See the "Split-DNS / MagicDNS" section
+# of the devs Tailscale docs (docs/tailscale-setup.md) for the why.
+set -uo pipefail
+
+RESOLV=/etc/resolv.conf
+MAGICDNS=100.100.100.100
+SOCK=/var/run/tailscale/tailscaled.sock
+
+# No-op unless Tailscale is actually up — otherwise we'd point the resolver at an
+# unreachable server and stall every lookup behind a timeout.
+if [ ! -S "$SOCK" ] || ! /usr/local/bin/tailscale --socket="$SOCK" status >/dev/null 2>&1; then
+  echo "ℹ️  Tailscale not up — skipping MagicDNS resolv.conf setup."
+  exit 0
+fi
+
+# Already prepended? (an uncommented `nameserver 100.100.100.100` line)
+if grep -qE "^[[:space:]]*nameserver[[:space:]]+${MAGICDNS}([[:space:]]|\$)" "$RESOLV"; then
+  echo "✅ MagicDNS resolver already present in $RESOLV — nothing to do."
+  exit 0
+fi
+
+# Prepend as the first nameserver. glibc reads nameserver lines in order and, on
+# MagicDNS SERVFAIL for non-tailnet names, falls through to the ISP servers that
+# remain below. /etc/resolv.conf is a Docker bind mount, so we rewrite it in place
+# (truncate + write) rather than mv'ing a new file over the mounted inode.
+new=$({ printf 'nameserver %s\n' "$MAGICDNS"; cat "$RESOLV"; })
+printf '%s\n' "$new" > "$RESOLV"
+echo "✅ Prepended MagicDNS resolver ($MAGICDNS) to $RESOLV for tailnet split-DNS."

devs_common-5.0.0/devs_common/templates/sudo-scripts/start-tailscaled.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Root helper (NOPASSWD sudo-script): start tailscaled as a detached daemon if it
+# isn't already running. Runs as root so Tailscale SSH can open login sessions;
+# uses userspace networking so no TUN device is required. Idempotent.
+set -uo pipefail
+
+SOCK="/var/run/tailscale/tailscaled.sock"
+
+# Idempotency / self-heal. Only skip if a tailscaled is ACTUALLY running. A plain
+# container restart (host reboot, `docker start`) re-runs only PID 1 — the daemon
+# process is gone, but its socket file persists on the container's writable layer.
+# A naive "socket exists => already up" check then sees that stale socket, skips
+# startup, and every subsequent `tailscale up` fails with "failed to connect to
+# local tailscaled". So probe for a live daemon; if the socket is stale, remove it
+# and start fresh.
+if [ -S "$SOCK" ]; then
+  if pgrep -x tailscaled >/dev/null 2>&1; then
+    exit 0   # a real daemon is running — nothing to do
+  fi
+  echo "Removing stale tailscaled socket (no tailscaled process is running)…"
+  rm -f "$SOCK"
+fi
+
+# setsid + </dev/null detaches the daemon from the calling exec session so it
+# survives after postCreate (or whoever invoked it) exits.
+setsid /usr/local/bin/tailscaled \
+  --tun=userspace-networking \
+  --socket="$SOCK" \
+  --statedir=/var/lib/tailscale \
+  </dev/null >>/var/log/tailscaled.log 2>&1 &
+disown 2>/dev/null || true
+
+for _ in $(seq 1 30); do
+  [ -S "$SOCK" ] && break
+  sleep 0.5
+done

devs_common-5.0.0/devs_common/templates/sudo-scripts/ts-cli.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# Root helper (NOPASSWD sudo-script): run the tailscale CLI against the container's
+# root daemon socket. The node-user `ts` wrapper calls this; start-tailscale.sh
+# uses it for up/serve/status.
+exec /usr/local/bin/tailscale --socket=/var/run/tailscale/tailscaled.sock "$@"

{devs_common-4.0.4 → devs_common-5.0.0}/devs_common/utils/devcontainer.py

@@ -54,6 +54,9 @@ def prepare_devcontainer_environment(
         'DEVCONTAINER_NAME': dev_name,
         'GIT_REMOTE_URL': git_remote_url,
         'WORKSPACE_FOLDER_NAME': workspace_folder_name,
+        # org-repo form (e.g. "myorg-myapp"); used to build a tailnet
+        # hostname like <project>-<dev>, stable across live/copy modes.
+        'DEVS_PROJECT_NAME': project_name,
     })
     
     # Set environment mount path (uses project-specific if exists, else default)

{devs_common-4.0.4 → devs_common-5.0.0}/devs_common.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devs-common
-Version: 4.0.4
+Version: 5.0.0
 Summary: Shared utilities for devs package ecosystem
 Author: Dan Lester
 License-Expression: MIT

{devs_common-4.0.4 → devs_common-5.0.0}/devs_common.egg-info/SOURCES.txt

@@ -15,7 +15,11 @@ devs_common/core/container.py
 devs_common/core/project.py
 devs_common/core/workspace.py
 devs_common/templates/Dockerfile
+devs_common/templates/README-vscode-settings.md
 devs_common/templates/devcontainer.json
+devs_common/templates/machine-settings.json
+devs_common/templates/machine-settings.tmux.json
+devs_common/templates/register-vscode-extensions.js
 devs_common/templates/vscode-settings-reference.md
 devs_common/templates/extensions/README.md
 devs_common/templates/extensions/devs-bridge-drop.vsix
@@ -23,16 +27,23 @@ devs_common/templates/extensions/install.sh
 devs_common/templates/scripts/copy-ssh.sh
 devs_common/templates/scripts/install-bridge-drop.sh
 devs_common/templates/scripts/post-create-wrapper.sh
+devs_common/templates/scripts/post-start.sh
 devs_common/templates/scripts/python-venv-integration.sh
 devs_common/templates/scripts/screenshot-webapp.sh
+devs_common/templates/scripts/setup-vscode-settings.sh
 devs_common/templates/scripts/setup-workspace.sh
+devs_common/templates/scripts/start-tailscale.sh
 devs_common/templates/scripts/start-tunnel.sh
+devs_common/templates/scripts/ts.sh
 devs_common/templates/scripts/tunnel-status.sh
 devs_common/templates/scripts/webapp-screenshot.py
 devs_common/templates/sudo-scripts/init-firewall.sh
 devs_common/templates/sudo-scripts/setup-devs-env.sh
+devs_common/templates/sudo-scripts/setup-magicdns.sh
 devs_common/templates/sudo-scripts/setup-vscode-cache.sh
 devs_common/templates/sudo-scripts/start-services.sh
+devs_common/templates/sudo-scripts/start-tailscaled.sh
+devs_common/templates/sudo-scripts/ts-cli.sh
 devs_common/utils/__init__.py
 devs_common/utils/config_hash.py
 devs_common/utils/console.py

{devs_common-4.0.4 → devs_common-5.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devs-common"
-version = "4.0.4"
+version = "5.0.0"
 description = "Shared utilities for devs package ecosystem"
 authors = [
     {name = "Dan Lester"},