@mdulghier/devtree 0.1.5

package/dist/vite.js

@@ -0,0 +1,72 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+function create_core_devtree_plugin() {
+    return {
+        name: "devtree",
+        apply: "serve",
+        config(user_config) {
+            const next_config = {};
+            const tailscale_host = process.env.DEVTREE_TAILSCALE_HOST?.trim();
+            if (!user_config.server?.host) {
+                next_config.server = {
+                    ...user_config.server,
+                    host: "127.0.0.1",
+                };
+            }
+            if (tailscale_host && user_config.server?.allowedHosts !== true) {
+                const allowed_hosts = user_config.server?.allowedHosts ?? [];
+                if (!allowed_hosts.includes(tailscale_host)) {
+                    next_config.server = {
+                        ...next_config.server,
+                        ...user_config.server,
+                        allowedHosts: [...allowed_hosts, tailscale_host],
+                    };
+                }
+            }
+            if (user_config.clearScreen === undefined) {
+                next_config.clearScreen = false;
+            }
+            return next_config;
+        },
+        configResolved(resolved_config) {
+            if (process.env.VITEST === "true" || process.env.NODE_ENV === "test") {
+                return;
+            }
+            if (resolved_config.command !== "serve") {
+                return;
+            }
+            if (process.env.DEVTREE_ACTIVE === "1") {
+                console.log(`[devtree] URL ${process.env.DEVTREE_PUBLIC_URL ?? "unknown"}`);
+                console.log(`[devtree] Instance ${process.env.DEVTREE_INSTANCE_ID ?? "unknown"}`);
+                return;
+            }
+            console.warn("[devtree] Run `vp run devtree dev` for isolated multi-instance development.");
+        },
+    };
+}
+export async function devtree_vite_plugins(config) {
+    const plugins = [create_core_devtree_plugin()];
+    if (config.env.provider !== "varlock") {
+        return plugins;
+    }
+    const package_name = "@varlock/vite-integration";
+    try {
+        const imported_module = (await import(__rewriteRelativeImportExtension(package_name)));
+        if (!imported_module.varlockVitePlugin) {
+            throw new Error(`Expected varlockVitePlugin export from ${package_name}.`);
+        }
+        plugins.unshift(imported_module.varlockVitePlugin({ ssrInjectMode: "init-only" }));
+        return plugins;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Varlock mode is enabled, but ${package_name} could not be loaded. ${message}`);
+    }
+}
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@mdulghier/devtree",
+  "version": "0.1.5",
+  "description": "Worktree-aware multi-instance dev orchestration for Vite+ apps.",
+  "keywords": [
+    "devtree",
+    "portless",
+    "varlock",
+    "vite",
+    "vite-plus",
+    "worktree",
+    "tanstack-intent"
+  ],
+  "homepage": "https://github.com/mdulghier/devtree#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdulghier/devtree.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mdulghier/devtree/issues"
+  },
+  "license": "UNLICENSED",
+  "bin": {
+    "devtree": "./bin/devtree.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "ci": "npm run check && npm test && npm run build",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "vp test run src/*.test.ts"
+  },
+  "dependencies": {
+    "dotenv": "^17.3.1",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "@tanstack/intent": "^0.0.23",
+    "typescript": "^5.7.2",
+    "vite-plus": "latest"
+  },
+  "peerDependencies": {
+    "@varlock/vite-integration": "*",
+    "varlock": "*",
+    "vite-plus": "*"
+  },
+  "peerDependenciesMeta": {
+    "@varlock/vite-integration": {
+      "optional": true
+    },
+    "varlock": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@10.32.1"
+}

package/skills/devtree-run-and-operate-devtree/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: devtree-run-and-operate-devtree
+description: >
+  Run and troubleshoot daily devtree workflows: `doctor`, `setup`, `dev`,
+  `info`, `env write`, `env show`, `deps start|stop|logs`, and `gc`. Load
+  this when an agent needs to verify that the app is running, reachable at
+  the worktree URL, and cleaned up correctly after worktrees are deleted.
+type: core
+library: devtree
+library_version: "0.1.0"
+sources:
+  - "mdulghier/devtree:README.md"
+  - "mdulghier/devtree:src/cli.ts"
+  - "mdulghier/devtree:src/command-builder.ts"
+  - "mdulghier/devtree:src/gc.ts"
+  - "mdulghier/devtree:src/registry.ts"
+  - "mdulghier/devtree:src/process.ts"
+  - "mdulghier/devtree:src/instance.ts"
+---
+
+# Devtree - Run And Operate
+
+## Setup
+
+Use the CLI in this order when bringing up a worktree instance.
+
+```bash
+pnpm devtree doctor --fix
+pnpm devtree setup
+pnpm devtree dev
+```
+
+Then inspect the assigned URL and names.
+
+```bash
+pnpm devtree info
+```
+
+For cleanup and dependency inspection:
+
+```bash
+pnpm devtree deps logs
+pnpm devtree gc --dry-run
+```
+
+## Core Patterns
+
+### Verify health with doctor first
+
+```bash
+pnpm devtree doctor --fix
+```
+
+Use `doctor` as the first check; it validates local prerequisites and bootstraps `portless` when needed.
+
+### Bring up dependencies before the dev server
+
+```bash
+pnpm devtree setup
+pnpm devtree dev
+```
+
+`setup` writes env overrides, starts configured dependencies, and runs setup hooks before `dev` starts the app.
+
+### Inspect the current instance URL and names
+
+```bash
+pnpm devtree info
+```
+
+`info` prints the public URL, app name, instance ID, scoped name, worktree path, env provider, env file, and Compose project names.
+
+### Clean up orphaned Docker resources safely
+
+```bash
+pnpm devtree gc --dry-run
+pnpm devtree gc
+```
+
+Dry-run first, then remove orphaned dependency resources created by deleted worktrees.
+
+## Common Mistakes
+
+### CRITICAL Start Vite directly instead of devtree
+
+Wrong:
+
+```json
+{
+  "scripts": {
+    "dev": "vp dev"
+  }
+}
+```
+
+```bash
+pnpm dev
+```
+
+Correct:
+
+```json
+{
+  "scripts": {
+    "devtree": "devtree"
+  }
+}
+```
+
+```bash
+pnpm devtree dev
+```
+
+Starting raw Vite skips devtree's portless wrapping and runtime env injection, so multi-worktree isolation disappears.
+
+Source: `README.md`, `src/command-builder.ts:17`
+
+### HIGH Disable portless and expect APP_URL to exist
+
+Wrong:
+
+```bash
+PORTLESS=0 pnpm devtree dev
+```
+
+Correct:
+
+```bash
+BETTER_AUTH_URL=http://localhost:3000 PORTLESS=0 pnpm devtree dev
+```
+
+When portless is disabled, devtree does not inject the public URL, so callback-based auth flows need an explicit fallback URL.
+
+Source: `src/cli.ts:499`
+
+### HIGH Skip setup when dependencies or hooks matter
+
+Wrong:
+
+```bash
+pnpm devtree dev
+```
+
+Correct:
+
+```bash
+pnpm devtree setup
+pnpm devtree dev
+```
+
+`dev` starts the app, but `setup` is what starts dependencies and runs `setup`, `migrate`, and `post_setup` hooks.
+
+Source: `README.md`, `src/cli.ts:448`
+
+### MEDIUM Assume gc removes unknown docker projects
+
+Wrong:
+
+```bash
+pnpm devtree gc
+```
+
+Correct:
+
+```bash
+pnpm devtree gc --dry-run
+```
+
+Unknown projects without worktree metadata are reported and skipped, so `gc` is not a universal Docker janitor.
+
+Source: `src/gc.ts:356`
+
+### HIGH Tension: portless compatibility versus public URL correctness
+
+Disabling portless can simplify local bootstrapping in odd environments, but it removes the stable public URL contract that devtree normally provides. Agents that take the shortcut need to replace that URL explicitly.
+
+See also: `devtree-set-up-devtree` - setup choices around portless and env injection decide whether runtime URLs work.
+
+See also: `devtree-set-up-devtree` - configuration drives most runtime failures.

package/skills/devtree-set-up-devtree/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: devtree-set-up-devtree
+description: >
+  Set up devtree in a Vite+ repository: install `devtree`, create
+  `devtree.config.ts`, define `env.entries`, choose `dotenv` or `varlock`,
+  register `devtree_vite_plugins`, and configure optional `dependencies`
+  and `hooks`. Load this when an agent needs to bootstrap worktree-aware
+  local development without URL, env, or Docker naming collisions.
+type: core
+library: devtree
+library_version: "0.1.0"
+sources:
+  - "mdulghier/devtree:README.md"
+  - "mdulghier/devtree:src/config.ts"
+  - "mdulghier/devtree:src/cli.ts"
+  - "mdulghier/devtree:src/vite.ts"
+  - "mdulghier/devtree:src/env-file.ts"
+  - "mdulghier/devtree:src/instance.ts"
+---
+
+# Devtree - Set Up
+
+## Setup
+
+Install `devtree` and register both the config file and the Vite plugin.
+
+```bash
+pnpm add -D devtree vite-plus
+```
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'dotenv',
+    entries: ({ instance }) => [
+      {
+        kind: 'value',
+        key: 'APP_URL',
+        value: instance.public_url,
+      },
+      {
+        kind: 'value',
+        key: 'DATABASE_PORT',
+        value: String(instance.allocate_port('postgres', 5400)),
+      },
+    ],
+  },
+})
+```
+
+```ts
+import { defineConfig } from 'vite-plus'
+import { devtree_vite_plugins } from 'devtree/vite'
+
+import devtree_config from './devtree.config.ts'
+
+export default defineConfig({
+  plugins: [...(await devtree_vite_plugins(devtree_config))],
+})
+```
+
+```json
+{
+  "scripts": {
+    "devtree": "devtree"
+  }
+}
+```
+
+```bash
+pnpm devtree doctor --fix
+pnpm devtree setup
+```
+
+## Core Patterns
+
+### Keep env values instance-derived
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'dotenv',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+      {
+        kind: 'value',
+        key: 'REDIS_PORT',
+        value: String(instance.allocate_port('redis', 6300)),
+      },
+    ],
+  },
+})
+```
+
+Use `instance.public_url`, `instance.get_scoped_name()` and `instance.allocate_port()` instead of fixed local values.
+
+### Start Docker dependencies through config
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'dotenv',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+    ],
+  },
+  dependencies: [
+    {
+      kind: 'compose',
+      name: 'postgres',
+      file_path: 'docker-compose.yml',
+      project_name: ({ instance }) => instance.get_scoped_name('db'),
+      services: ['db'],
+    },
+  ],
+})
+```
+
+Compose dependencies are the default way to give each worktree isolated container, network, and volume names.
+
+### Use hooks for repo-specific setup
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'dotenv',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+    ],
+  },
+  hooks: {
+    migrate: [
+      {
+        command: ['pnpm', 'db:migrate'],
+      },
+    ],
+    pre_dev: [
+      {
+        command: ['pnpm', 'codegen'],
+      },
+    ],
+  },
+})
+```
+
+`setup` runs `setup`, `migrate`, and `post_setup`; `dev` runs `pre_dev` before starting the server.
+
+### Turn on varlock only with its prerequisites
+
+```bash
+pnpm add -D varlock @varlock/vite-integration
+touch .env.schema
+```
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'varlock',
+    schema_path: '.env.schema',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+    ],
+  },
+})
+```
+
+Keep the simple `dotenv` path as the default; use `varlock` when the repo already wants schema-based env handling.
+
+## Common Mistakes
+
+### CRITICAL Hard-code shared URLs and ports
+
+Wrong:
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'dotenv',
+    entries: () => [
+      { kind: 'value', key: 'APP_URL', value: 'http://localhost:3000' },
+      { kind: 'value', key: 'DATABASE_PORT', value: '5432' },
+    ],
+  },
+})
+```
+
+Correct:
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'dotenv',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+      {
+        kind: 'value',
+        key: 'DATABASE_PORT',
+        value: String(instance.allocate_port('postgres', 5400)),
+      },
+    ],
+  },
+})
+```
+
+Static values remove the per-worktree isolation that devtree is supposed to enforce.
+
+Source: `README.md`
+
+### HIGH Store manual values inside managed block
+
+Wrong:
+
+```dotenv
+# >>> devtree managed env >>>
+APP_URL=http://feature-x.my-app.localhost:1355
+STRIPE_SECRET_KEY=sk_live_manual_override
+# <<< devtree managed env <<<
+```
+
+Correct:
+
+```dotenv
+# >>> devtree managed env >>>
+APP_URL=http://feature-x.my-app.localhost:1355
+# <<< devtree managed env <<<
+
+STRIPE_SECRET_KEY=sk_live_manual_override
+```
+
+Devtree rewrites the managed block on each run and only preserves custom content outside that block.
+
+Source: `src/env-file.ts:78`
+
+### HIGH Force shared dependency project names
+
+Wrong:
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'dotenv',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+    ],
+  },
+  dependencies: [
+    {
+      kind: 'compose',
+      name: 'db',
+      project_name: 'my-app',
+    },
+  ],
+})
+```
+
+Correct:
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'dotenv',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+    ],
+  },
+  dependencies: [
+    {
+      kind: 'compose',
+      name: 'db',
+      project_name: ({ instance }) => instance.get_scoped_name('db'),
+    },
+  ],
+})
+```
+
+Static Compose project names silently make multiple worktrees fight over the same Docker resources.
+
+Source: `src/cli.ts:156`
+
+### HIGH Enable varlock without integration prerequisites
+
+Wrong:
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'varlock',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+    ],
+  },
+})
+```
+
+Correct:
+
+```bash
+pnpm add -D varlock @varlock/vite-integration
+touch .env.schema
+```
+
+```ts
+import { define_devtree_config } from 'devtree'
+
+export default define_devtree_config({
+  app_name: 'my-app',
+  env: {
+    provider: 'varlock',
+    schema_path: '.env.schema',
+    entries: ({ instance }) => [
+      { kind: 'value', key: 'APP_URL', value: instance.public_url },
+    ],
+  },
+})
+```
+
+`varlock` mode depends on the CLI, the schema file, and `@varlock/vite-integration`; missing any of them breaks setup or plugin loading.
+
+Source: `src/cli.ts:338`, `src/vite.ts:45`
+
+### HIGH Tension: simple setup versus explicit override freedom
+
+Devtree works best when it owns URL, env, and dependency naming. Agents trying to be “helpful” by hard-coding familiar local values usually delete the whole point of the library.
+
+See also: `devtree-run-and-operate-devtree` - runtime checks expose the fallout from setup shortcuts.