@haus-tech/haus-workflow 6.2.0 → 6.3.0

package/library/global/skills/haus-workflow/references/clone.md

@@ -202,6 +202,142 @@ seeds: # optional: data sources NOT owned by a manifest repo (e.g. a shared Word
         login: 'Add your SSH key to the host (ssh-add …) / request access — or skip the pull.'
 ```
 
+**Workspace, format v2: the `instance:` section (per-worktree environments, ADR-0163).**
+A workspace that runs features in parallel worktrees adds `version: 2` and an `instance:`
+section, and sets `worktree.env: true` in `haus.workspace.yaml`. Unlike the rest of this
+file, `instance:` is parsed and validated strictly by the CLI (`haus doctor`; schema
+`library/schemas/localdev.v2.schema.json`); unknown keys are errors. A v1 file simply has
+no instance support.
+
+```yaml
+version: 2
+instance:
+  ports: # name -> main-checkout port; a worktree gets <leased block> + offset, in this order
+    vendure: 3000
+    admin-ui: 4200
+  datastores: # shared engines; a worktree is isolated INSIDE them, never by its own container
+    mariadb: { engine: mariadb, compose: { project: shop-workspace, service: mariadb }, port: 3318 }
+    # compose.file: the compose file (workspace-relative) when its name is not a default one,
+    # e.g. compose: { project: shop-workspace, service: pg, file: docker-compose.local.yml }
+    redis: { engine: redis, compose: { project: shop-workspace, service: redis }, port: 6381 } # needs --databases 64
+    search:
+      {
+        engine: elasticsearch,
+        compose: { project: shop-workspace, service: es },
+        port: 9201,
+        prefix: 'vendure-',
+      }
+  databases: # one database per worktree: <name>_wt_<slug>, cloned from <name>_tpl (or <name>)
+    ecom: { on: mariadb, name: shop_ecom, perWorktree: clone } # or perWorktree: empty
+  sites: # one Herd site per worktree on a copy-on-write docroot clone
+    wordpress:
+      kind: herd
+      root: shop.se # workspace-relative docroot
+      host: '{{slug}}.shop.se' # served at http://<slug>.shop.se.test
+      share: [wp-content/uploads] # symlinked to the main docroot, not copied
+      plugins: { ecom-widgets: shop-ecom-widgets } # plugin dir -> member repo in this worktree
+      config:
+        {
+          kind: wp-config-override,
+          defines: { DB_NAME: '{{db.wp}}', WP_HOME: '{{site.wordpress.url}}' },
+        }
+      after: ['wp search-replace http://shop.se.test {{site.wordpress.url}} --skip-columns=guid']
+  processes: # what `env start <name>` runs, from that member repo, on its leased port
+    vendure: { repo: shop-ecom, start: 'yarn dev', port: vendure, health: '/health' }
+  copyLocal: # extra machine-local files copied from the main checkout (mode 600)
+    - { repo: shop-ecom, path: auth.json }
+  teardown: # shell commands `env down --destroy` / `env gc --write` run before dropping databases
+    - 'docker compose -p shop-ecom-e2e-{{slug}} down -v --remove-orphans'
+env: # the same map as v1; values may now use templates
+  - value: '{{port.vendure}}'
+    sinks: [{ repo: shop-ecom, key: API_PORT }]
+  - value: '{{db.ecom}}'
+    sinks: [{ repo: shop-ecom, key: DB_NAME }]
+  - value: '{{redis.redis.db}}'
+    sinks: [{ repo: shop-ecom, key: REDIS_DB }]
+```
+
+Templates: `{{slug}}`, `{{port.<name>}}`, `{{db.<name>}}`, `{{redis.<name>.db}}`,
+`{{search.<name>.prefix}}`, `{{site.<name>.url|host|root}}`. In the main checkout they
+resolve to today's values (the main ports and database names, Redis DB 0, the main
+prefix), so one manifest serves both; only a worktree gets new ones. Only keys fed by a
+templated entry are instance-owned; every other key in a repo's `.env` is copied as it is.
+`teardown` (workspace file only) cleans up per-worktree resources the CLI does not track,
+such as a compose project an app's own test harness starts; keep each command idempotent.
+`after` (workspace file only) is its counterpart for `env up`: commands that run once per
+environment in the worktree root, after the `.env` files and `.haus-env.json` exist, such as
+copying the main bucket into a per-worktree one (`mc mirror local/assets
+local/assets-wt-{{slug}}`); a failed one is retried by the next `env up`.
+
+**Single-repo projects** (a plain repo with Claude Code worktrees, ADR-0167): the repo's own
+`.haus-workflow/localdev.yml` takes the whole `instance:` section, the flag is
+`"worktree": { "env": true }` in `.haus-workflow/haus.config.json`, and `repo:` in sinks,
+processes and `copyLocal` names a folder inside the repo (`.` for the root, `apps/server`
+for an app).
+
+**Other engines and site kinds.** The same section covers the other client stacks:
+
+```yaml
+instance:
+  datastores:
+    # An engine on the host (DBngin, Homebrew), not in Docker: haus never starts it and
+    # connects with the host's mysql/mariadb client. Credentials: export MYSQL_USER and
+    # MYSQL_PWD, or use ~/.my.cnf. `port` defaults to native.port. Supported for mariadb,
+    # mysql, elasticsearch and opensearch.
+    mysql: { engine: mysql, native: { host: 127.0.0.1, port: 3306 } }
+    #   native: { host: 127.0.0.1, port: 3306, client: /Users/Shared/DBngin/mysql/8.0.33/bin/mysql }
+    # SQL Server: database isolation (BACKUP / RESTORE WITH MOVE into <name>_wt_<slug>).
+    # azure-sql-edge has no sqlcmd; haus then runs mcr.microsoft.com/mssql-tools (amd64) on
+    # the engine's network. The SA password stays in the engine container's env.
+    mssql: { engine: mssql, compose: { project: vafab-workspace, service: mssql }, port: 49760 }
+  sites:
+    cms: # Bedrock: the root is a member repo, its .env gets the defines (copy: none is the default)
+      kind: herd
+      root: bad-varme.se
+      host: '{{slug}}.bad-varme.se'
+      php: '8.2'
+      share: [web/app/uploads]
+      config:
+        kind: bedrock-env
+        defines:
+          DB_NAME: '{{db.wp}}'
+          WP_HOME: '{{site.cms.url}}'
+          WP_SITEURL: '{{site.cms.url}}/wp'
+    app: # Laravel on Herd: same, with Laravel's keys
+      kind: herd
+      root: app.example.se
+      host: '{{slug}}.app.example.se'
+      secure: true
+      config:
+        kind: laravel-env
+        defines: { APP_URL: '{{site.app.url}}', DB_DATABASE: '{{db.api}}' }
+```
+
+`bedrock-env` and `laravel-env` write no PHP file and need no `patch-wp-config`: the
+defines become instance-owned keys of the member's `.env`, next to any `env:` sinks for
+that repo, and the rest of the main checkout's `.env` is copied as it is. Teardown unlinks
+the Herd site and never deletes the member repo.
+
+**How this relates to the clone flow.** This procedure sets up the **main checkout**: it
+brings the shared engines up, seeds the main databases and writes each repo's `.env`. It
+never touches `instance:`. A worktree then gets its own environment from that main
+checkout with one command, run inside the worktree:
+
+```bash
+haus workspace worktree env snapshot ecom   # once, and whenever fresh data is wanted: <name>_tpl from the main DB
+haus workspace worktree env up              # lease ports, clone DBs, Redis index, prefix, site, .env files
+haus workspace worktree env start vendure   # runs on the worktree's own port
+haus workspace worktree env status          # ports, URLs, databases
+haus workspace worktree env down --destroy  # or just `worktree remove`, which runs it first
+```
+
+`env up` copies each repo's `.env` from the main checkout (secrets included, never printed)
+and replaces only the instance-owned keys, so the main checkout's `.env` must exist first:
+that is exactly what this clone flow produces. Agents never read a `.env`; they use
+`haus workspace worktree env get <key>` or `.haus-env.json`. For a WordPress site with
+`config.kind: wp-config-override`, run `haus workspace worktree env patch-wp-config <site>`
+once in the main checkout (it backs the file up and never prints it).
+
 #### Run order
 
 1. **Discover** `.haus-workflow/localdev.yml` in the workspace root and each repo.

package/library/schemas/localdev.v2.schema.json

@@ -0,0 +1,369 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/WeAreHausTech/haus-workflow/library/schemas/localdev.v2.schema.json",
+  "title": "haus localdev.yml (version 2)",
+  "description": "The CLI-parsed part of .haus-workflow/localdev.yml (ADR-0163). Only `version`, `instance` and the templates in `env` are validated by the CLI (src/workspace/env/manifest.ts, which is the enforcement); every other top-level key is agent-interpreted by the clone skill and left open here. Templates: {{slug}}, {{port.<name>}}, {{db.<name>}}, {{redis.<name>.db}}, {{search.<name>.prefix}}, {{site.<name>.url|host|root}}.",
+  "type": "object",
+  "properties": {
+    "version": {
+      "enum": [1, 2]
+    },
+    "instance": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-worktree environment. A repo file may declare only ports and processes.",
+      "properties": {
+        "ports": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$"
+          },
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535
+          },
+          "maxProperties": 20,
+          "description": "name -> main-checkout port; a worktree gets lease base + declaration index"
+        },
+        "datastores": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["engine"],
+            "properties": {
+              "engine": {
+                "enum": [
+                  "mariadb",
+                  "mysql",
+                  "postgres",
+                  "redis",
+                  "elasticsearch",
+                  "opensearch",
+                  "mssql"
+                ]
+              },
+              "compose": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["project", "service"],
+                "properties": {
+                  "project": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "service": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "file": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Compose file, relative to the workspace root, passed as -f when env up has to create the engine (for a non-default name such as docker-compose.local.yml)."
+                  }
+                }
+              },
+              "native": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["host", "port"],
+                "description": "An engine on the host, outside Docker (mariadb, mysql, elasticsearch, opensearch). haus never starts it; SQL credentials come only from MYSQL_USER / MYSQL_PWD or ~/.my.cnf.",
+                "properties": {
+                  "host": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9._:-]+$"
+                  },
+                  "port": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 65535
+                  },
+                  "client": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9._/+-]+$",
+                    "description": "mysql/mariadb client: a command on PATH or an absolute path (default: mysql or mariadb on PATH)"
+                  }
+                }
+              },
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535,
+                "description": "The engine port. Optional with native: (defaults to native.port)."
+              },
+              "isolation": {
+                "enum": ["database", "db-index", "key-prefix", "prefix", "container"],
+                "description": "Default per engine: database (SQL, mssql included), db-index (redis), prefix (search). container has no driver yet."
+              },
+              "prefix": {
+                "type": "string",
+                "description": "The main checkout's index or key prefix (default empty)."
+              }
+            },
+            "oneOf": [
+              {
+                "required": ["compose", "port"]
+              },
+              {
+                "required": ["native"]
+              }
+            ]
+          }
+        },
+        "databases": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["on", "name"],
+            "properties": {
+              "on": {
+                "type": "string",
+                "description": "A datastore name"
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "perWorktree": {
+                "enum": ["clone", "empty"],
+                "default": "clone"
+              }
+            }
+          }
+        },
+        "sites": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "root", "host"],
+            "properties": {
+              "kind": {
+                "const": "herd"
+              },
+              "mode": {
+                "enum": ["per-worktree", "shared-lock"],
+                "default": "per-worktree"
+              },
+              "root": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Relative path inside the repo; no leading / and no .."
+              },
+              "host": {
+                "type": "string",
+                "minLength": 1,
+                "description": "May use templates, e.g. {{slug}}.shop.se"
+              },
+              "mainHost": {
+                "type": "string",
+                "description": "The main checkout's host (default: basename of root)"
+              },
+              "secure": {
+                "type": "boolean",
+                "default": false
+              },
+              "php": {
+                "type": ["string", "number"]
+              },
+              "copy": {
+                "enum": ["cow", "none"],
+                "description": "cow clones the main docroot; none uses the worktree folder as it is (the default, and required, for bedrock-env and laravel-env, whose root is a member repo)."
+              },
+              "share": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "plugins": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "config": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind"],
+                "properties": {
+                  "kind": {
+                    "enum": ["wp-config-override", "bedrock-env", "laravel-env"],
+                    "description": "wp-config-override writes wp-config.haus-instance.php; bedrock-env and laravel-env write the defines into the site repo's .env (instance-owned keys)."
+                  },
+                  "defines": {
+                    "type": "object",
+                    "propertyNames": {
+                      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                    },
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  }
+                }
+              },
+              "after": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
+        },
+        "processes": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["start"],
+            "properties": {
+              "repo": {
+                "type": "string",
+                "description": "Required in the workspace file; defaults to the owning repo in a repo file. In a single-repo project (ADR-0167), the folder inside the repo the process runs in (`.` for the root)"
+              },
+              "start": {
+                "type": "string",
+                "minLength": 1
+              },
+              "port": {
+                "type": "string",
+                "description": "A name from instance.ports"
+              },
+              "health": {
+                "type": "string"
+              },
+              "healthTimeoutSec": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 120
+              },
+              "optional": {
+                "type": "boolean",
+                "default": false
+              }
+            }
+          }
+        },
+        "copyLocal": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["repo", "path"],
+            "properties": {
+              "repo": {
+                "type": "string",
+                "minLength": 1
+              },
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Relative path inside the repo; no leading / and no .."
+              }
+            }
+          }
+        },
+        "teardown": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Shell commands (templated) env down --destroy and env gc --write run after stopping processes and before dropping databases; workspace file only, must be idempotent"
+        },
+        "after": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Shell commands (templated) env up runs once per environment in the worktree root, after the .env files and .haus-env.json are written (for example seeding a per-worktree bucket from the main one, ADR-0167); a failed one is retried by the next env up; workspace file only, must be idempotent"
+        }
+      }
+    },
+    "env": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["sinks"],
+        "properties": {
+          "value": {
+            "type": ["string", "number"]
+          },
+          "source": {
+            "type": "object",
+            "required": ["provides"],
+            "properties": {
+              "repo": {
+                "type": "string"
+              },
+              "provides": {
+                "type": "string"
+              }
+            }
+          },
+          "sinks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["repo", "key"],
+              "properties": {
+                "repo": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "A member repo (id or folder) in a workspace; in a single-repo project (ADR-0167) a folder inside the repo in canonical form, `.` for the root or `apps/server` for a monorepo app, whose .env receives the key"
+                },
+                "key": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                }
+              }
+            }
+          }
+        },
+        "anyOf": [
+          {
+            "required": ["value"]
+          },
+          {
+            "required": ["source"]
+          }
+        ]
+      }
+    }
+  },
+  "if": {
+    "required": ["instance"]
+  },
+  "then": {
+    "properties": {
+      "version": {
+        "const": 2
+      }
+    },
+    "required": ["version"]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haus-tech/haus-workflow",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "Haus AI workflow CLI for Claude Code.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "scripts/postinstall.mjs",
     "library/global",
     "library/catalog",
+    "library/schemas",
     "README.md",
     "CHANGELOG.md",
     "docs/before-you-start.md",
@@ -28,6 +29,7 @@
     "test:quick": "node scripts/test-fast.mjs --quick",
     "test:full": "node scripts/run-tests.mjs tests/**/*.test.js",
     "test:coverage": "c8 yarn test:full",
+    "test:integration": "HAUS_INTEGRATION=1 node scripts/run-tests.mjs tests/integration/*.int.test.js",
     "coverage:check": "c8 --check-coverage yarn test:full",
     "lint": "eslint src --cache --cache-location .eslintcache",
     "format:check": "prettier --check --cache --cache-location .prettiercache .",