@webship.co/workspace 0.0.0-stage → 1.0.0-alpha1

package/PLUGINS.md

@@ -0,0 +1,249 @@
+# Dashboard plugins
+
+Optional features, each a package of its own, turned on in four steps. The lean core is the
+workspaces, the builders, the settings and the assistant shell; everything else — Upsun, Jira, the
+Web IDE, git, tests, graphs, RAG, media, avatars, designs — is a plugin in its own repository
+(`github.com/webship/workspace-<name>`), required with npm when a machine needs it.
+
+```bash
+bash core/scripts/plugins.sh --require github:webship/workspace-upsun   # 1. require: npm install into the dashboard
+bash core/scripts/plugins.sh --activate upsun                            # 2. activate: plugins.upsun in settings.yml
+bash core/scripts/plugins.sh --install upsun                             # 3. install: place what the manifest names
+bash core/scripts/plugins.sh --configure upsun                           # 4. configure: its own settings file
+bash core/scripts/plugins.sh --list                                      # where each plugin is
+```
+
+The same four steps are buttons on **Settings → Plugins**. `--install` is idempotent, records what
+it placed in `core/config/plugins.installed.yml`, keeps a managed block in `.gitignore` so a dev
+clone never commits what an install placed, and says when the dashboard container needs
+`ddev restart` (a compose file or host mount the plugin brought). `--uninstall` removes exactly
+what `--install` placed.
+
+A plugin is a node package with a `workspacePlugin` manifest in its `package.json` and an
+`index.js` exporting `register(api)` — or a folder under `core/workspace-app/plugins/<name>/` with
+the same shape, which is how one is developed before it gets a repository.
+
+## The manifest
+
+```json
+"workspacePlugin": {
+  "name": "upsun",                                   // its settings key and route namespace
+  "label": "Upsun",
+  "settingsFile": "plugin.upsun.settings.yml",       // core/config/<file>, created from…
+  "settingsTemplate": "config/plugin.upsun.settings.yml",
+  "legacySettingsKey": "upsun",                      // the settings.yml block it replaces: its values carry over
+  "labels": "config/settings.labels.yml",            // labels for its settings keys, merged into the Settings page
+  "typeActions": { "upsun": ["sites"] },             // actions workspace types may allow
+  "commands": { "types": ["sites"], "workspaces": ["dev", "test"], "files": ["commands/cmd-tools-upsun.sh"] },
+  "scripts": { "functions": ["scripts/functions/fun-upsun.sh"], "args": ["scripts/args/arg-upsun.sh"],
+               "machine": ["scripts/upsun-ai.sh"], "hostInstall": "scripts/host-install.sh" },
+  "ddev": { "compose": ["ddev/docker-compose.upsun-cli.yaml"], "hostMounts": ["~/.upsun-cli"] },
+  "themes": ["config/theme.upsun.yml"],
+  "css": ["public/upsun.css"]
+}
+```
+
+Where each piece lands: functions, args and machine scripts in `core/scripts/plugins/<name>/`
+(bootstrap sources every `functions/*.sh` there, so a `cmd-*.sh` can call them; an args file is
+sourced as `${WORKSPACE_SCRIPTS}/plugins/<name>/args/<file>`); commands in every workspace the
+manifest names (or every one of its types), with `__WORKSPACE__` replaced by the folder's name;
+compose files as `core/workspace-app/.ddev/docker-compose.plugin-<name>-<file>`; host mounts in a
+`host-mounts.txt` that `host-mounts.sh` reads; themes in `core/config/`. `hostInstall` runs with
+`--check` after an install and in full from `install.sh`.
+
+Everything stays HTMX + UIKit: a plugin serves server-rendered fragments and wires them with
+`hx-get`/`hx-post`; no client frameworks.
+
+## A plugin is a node module
+
+A plugin can be a folder under `plugins/<name>/` or any npm package. A package is the way to share one: name
+it with `module:` and the loader requires it by name, **before** looking for a folder (the folder is the fallback
+when the package is not installed yet). To ship one inside this repo, keep it in `plugins/<name>/` with its own
+`package.json` and link it from the dashboard's:
+
+```json
+"dependencies": { "@webship.co/workspace-google-drive": "file:plugins/google-drive-sync" }
+```
+
+```yaml
+plugins:
+  google-drive-sync:
+    enabled: true
+    module: "@webship.co/workspace-google-drive"
+```
+
+`npm install` links it into `node_modules`. `plugins/google-drive-sync` is the worked example: `index.js`
+(`register(api)`), `lib/`, its own `tests/` (picked up by `npm run test:unit`), and a rule its tests enforce:
+**require nothing outside the package**. Anything the command line or an MCP server of yours also runs must work
+without the dashboard, so reach the dashboard only through `api`.
+
+## A plugin's own settings file
+
+Each plugin keeps its settings in `core/config/plugin.<name>.settings.yml`, not in `settings.yml`: edited,
+backed up and protected separately (the file is created mode 600, and `client_secret`, `token` and similar keys
+are masked on the Settings page like any secret), and gone when the plugin is. `sync-tooling` never copies it.
+A plugin reads and writes it through `api.settings` and keeps a shipped template of it in `core/config/`.
+
+## Turn one on
+
+```yaml
+# core/config/settings.yml
+plugins:
+  workspace-notes:
+    enabled: true
+    workspaces: "dev,test"   # empty or absent = every workspace
+  my-npm-plugin:
+    enabled: true
+    module: "@webship/my-npm-plugin"
+```
+
+Restart the app (`docker exec ddev-workspace-web supervisorctl restart webextradaemons:workspace-app`) to load
+changes — plugins are read once at startup. A plugin that fails to load is reported on the
+console and skipped; it cannot take the dashboard down.
+
+## Write one
+
+```js
+// core/workspace-app/plugins/hello/index.js
+module.exports.register = (api) => {
+  const { esc, workspaceDir, isValidWorkspace } = api.lib;
+
+  // A rail button on every workspace page this plugin applies to.
+  api.addPageActions(({ view, key, meta }) => {
+    if (view !== 'workspace' || !key || !api.appliesTo(key)) return null;
+    return { label: 'Hello', items: [
+      `<button class="uk-button uk-button-default action-btn"
+        hx-get="/fragments/p/${api.name}/greet?workspace=${esc(key)}"
+        hx-target="#webship-workspace-output" hx-swap="innerHTML">
+        <span uk-icon="icon: happy; ratio: .8"></span><span class="action-label">Hello</span></button>`,
+    ] };
+  });
+
+  // GET /fragments/p/hello/<rest>
+  api.addFragment(({ send, rest, searchParams }) => {
+    send(`<div class="msg assistant">Hello from ${esc(searchParams.get('workspace') || '?')}.</div>`);
+  });
+
+  // POST /actions/p/hello/<action> — context is the same one built-in actions get.
+  api.addAction('save', ({ form, send, workspace }) => {
+    send('<div class="msg assistant">Saved.</div>');
+  });
+};
+```
+
+## The api
+
+| Member | What it is |
+| --- | --- |
+| `api.name` | The plugin's settings key. Also its route namespace. |
+| `api.config` | Its `plugins.<name>` block from settings.yml, verbatim. |
+| `api.appliesTo(key)` | Whether `config.workspaces` includes that workspace (empty list = all). |
+| `api.addAction(name, handler)` | POST handler at `/actions/p/<plugin>/<name>`. Context: `{ form, res, send, workspace, pathname }` — identical to built-in actions. |
+| `api.addFragment(handler)` | GET handler for `/fragments/p/<plugin>/<rest>`. Context: `{ req, res, send, rest, searchParams }`. |
+| `api.addPageActions(fn)` | `fn({ view, key, meta })` returns a rail group `{ label, items: [html] }` or null. Runs on every page render. |
+| `api.addProjectActions(fn)` | `fn({ key, project, dir, meta })` returns HTML appended to that project row's actions (or null). Runs per row on `projects`-kind pages. |
+| `api.addRowMenu(slot, { label, row }, fn)` | A named menu on every project row, in a slot the Buttons settings arrange like a built-in one. `fn({ key, project, dir, meta, allowed, vals })` returns the menu's HTML, or null for a row it has nothing for. |
+| `api.addPage(re, handler)` | A whole page: GET requests whose path matches `re`. `handler({ req, res, match, send })` writes the response itself. |
+| `api.addProjectChip(fn)` | A chip in the project card's meta line. `fn({ key, project, dir, meta })` returns HTML or null. |
+| `api.addFolderSetup({ html, steps, prompt, problem })` | A section of the New-folder form (`html(ws, { allowed })`), the shell steps it adds (`steps(ws, name, form, ctx)` → array), the lines it adds to the Claude Code prompt (`prompt(…)` → array) and its validation (`problem(ws, form, ctx)` → '' or why). |
+| `api.addTypeAction(action, types)` | What the manifest's `typeActions` does, from code. |
+| `api.addCss(file)` | A stylesheet appended after the components (what the manifest's `css` does). |
+| `api.addLabels(map)` | Labels for its settings keys (what the manifest's `labels` does). |
+| `api.addProjectBadge(fn)` | A badge in the project card's corner, sent with every screens poll so it clears itself. `fn({ key, project, dir, sessions })` returns HTML or null; `sessions` is the project's live screens. |
+| `api.addSettingsOptions(file, dotted, fn)` | Live options for a field of a settings file (what a CLI can see rather than a hand-typed key). `fn()` is async and returns `[value, label][]`, or null for a plain input. |
+| `api.addScreenStartHook(fn)` | Called after a screen session started for a work item (the New screen form's `work` key): `fn({ session, workKey, workspace, project, dir, form })` notes the run, posts if asked, returns HTML or ''. |
+| `api.addWorkKeyLink(fn)` | Where a work-item key found in a project's name links to: `fn(key)` returns a URL or null (the chip is plain text without one). |
+| `api.addWorkPrompt(fn)` | The prompt a screen started for a work item begins with: `fn({ key, workspace, project })` returns it, or null for the dashboard's own. |
+| `api.addSessionLog(fn)` | Where a session's log lives when the dashboard does not know: `fn(session, dirs)` returns a file in one of `dirs`, or ''. |
+| `api.addAssistantContext(fn)` | A paragraph of the assistant's system context: what this plugin lets it reach, and the rules. |
+
+`api.lib` also lends `tabModalHtml`, `hubDomain()`, `listScreens()`, `agentSessions()`, `screenLogFor()`, `claudeSessionsFor()` and
+`screensCached()` (the last `screen -ls`, for a renderer that cannot wait). The types of all of it are
+`@webship.co/workspace-plugin-api`; a plugin written in TypeScript is checked against them.
+
+## TypeScript
+
+A plugin package is TypeScript: `src/` compiled to `dist/` by `tsc` on install (`prepare`), so the dashboard
+requires `dist/src/index.js` and a clone of the repository builds itself. Its tests are TypeScript too
+and run compiled (`npm test`); `@webship.co/workspace-upsun` is the shape to copy.
+| `api.settings` | This plugin's own settings file: `file`, `read()`, `set(dotted, value)` and `setList(dotted, items)`, which change one key or list in place, comments kept, creating the file when it is missing. |
+| `api.lib` | Shared helpers: `esc`, `humanSize`, `humanTime`, `ROOT`, `loadWorkspaces`, `workspaceDir`, `isValidWorkspace`, `startJob`, `jobFragment`, `listProjects`, `NAME_RE`, `wsUrl` — `screenAction` (start a command as a Screen session, the way every long action does), `auth` (`sessionOf(req)`, `googleButton`, `BUTTON_CSS` from the dashboard's Google sign-in), plus the type layer: `TYPES`, `workspaceType(key)`, `typeAllows(key, action)`. |
+
+Namespacing is the safety model: a plugin's routes all live under its own name, so it can never
+shadow a built-in, and disabling it removes its whole surface at once.
+
+## Useful targets
+
+- `#webship-workspace-output` — the page's output area (results, job toasts land near it).
+- `#editor-modal-body` — the editor modal; anything swapped in opens it automatically.
+- `api.lib.startJob(title, cmd, args, cwd, opts)` + `jobFragment(id).html` — run a command as a
+  live job toast, the way every built-in long action does.
+
+## Types and plugins
+
+Workspace folders have a **type** (`sites`, `code`, `files`, `media`, `ai-items` — see
+`WORKSPACES.md`) that decides which built-in actions their project rows carry. A plugin can read
+the same layer to offer itself only where it makes sense:
+
+```js
+api.addProjectActions(({ key, project, meta }) => {
+  if (!api.appliesTo(key) || api.lib.workspaceType(key) !== 'sites') return null;
+  return `<button class="uk-button uk-button-default uk-button-small"
+    hx-post="/actions/p/${api.name}/ping" hx-vals='{"workspace":"${api.lib.esc(key)}","projectName":"${api.lib.esc(project)}"}'
+    hx-target="#webship-workspace-output" hx-swap="innerHTML">
+    <span uk-icon="icon: bolt; ratio: .7"></span> Ping</button>`;
+});
+```
+
+## A workspace as a plugin
+
+A workspace folder (modules, themes, recipes, dev, …) can itself be a plugin: the package carries
+the folder's `workspace.<key>.settings.yml` template, its `cmd-*.sh` commands and its docs, and the
+manifest names the folder:
+
+```json
+"workspacePlugin": {
+  "name": "drupal-themes",
+  "workspace": { "key": "themes", "settingsTemplate": "config/workspace.themes.settings.yml",
+                 "files": ["commands/cmd-build-theme.sh"], "docs": ["docs/AGENTS.md"] }
+}
+```
+
+`--install` makes the folder, places the settings file once (never overwritten: it holds this
+machine's lists) and the commands (`__WORKSPACE__` filled with the key), and writes the docs once.
+`--activate` puts the key on settings.yml's `workspaces:` list, at the end (the dashboard's order;
+move it in Settings → Workspaces); `--deactivate` takes it off, and the folder, its content and its
+settings stay. `--uninstall` removes the commands and keeps the settings file and the docs. The bash
+functions the commands call still live in `core/scripts/functions` (and in `scripts.functions` of
+the plugin, placed under `core/scripts/plugins/<name>/functions/`).
+
+## Hooks a feature plugin reaches for
+
+Besides the row menus, pages, fragments and actions, the loader offers: `addForge(host, …)` (the
+credential the dashboard uses for a git host: `github-auth.js` asks it first), `addOpenWith(fn)` (the
+Open-with menu for a folder: project rows, the files pages, the images gallery) and `addFolderLink(fn)`
+(a link that opens a folder elsewhere, inside the COMPOSER menu). `api.lib` also hands a plugin what
+git says about a folder (`hasOwnGit`, `gitWorktreeInfo`, `projectHasGit`, `gitBranchOf`), the
+lingering-session tail (`lingerTail`, `LINGER_MARK`), `tildePath` and `hostRunnerRequest`.
+
+## Families
+
+Plugins that do the same job for different services share a base package, so a provider is thin and
+the surface is one. A base is an ordinary private npm package the provider depends on; it is not a
+plugin itself (no manifest) and the dashboard never sees it.
+
+| Family | Base | What the base draws | A provider supplies |
+| --- | --- | --- | --- |
+| Hosting (`upsun`, `acquia`, `digitalocean`, `cpanel`, `aws`, `azure`, `godaddy`) | `@webship.co/workspace-hosting` — `registerHosting(api, provider)` | the per-provider row menu (linked / unlinked), the live-site chip, the environments modal and list, the get-database-and-files flow, the branch-and-data block, the tool verbs as screen sessions, the `/<id>-site/<ws>/<project>` jump, the New-folder section, the family stylesheet | a `HostingProvider`: how a project is detected as linked, the CLI and its token, the environments and their URLs, the verbs its `cmd-tools-<id>.sh` carries (status, activities, logs, deploy…), the pull flags, the console URL |
+
+| Forges (`github`, `gitlab`, `bitbucket`) | `@webship.co/workspace-forge` — `registerForge(api, forge)` | the credential the dashboard uses for the host (`api.addForge`, which `github-auth.js` asks before the legacy `git.github` block), the row menu on every project whose git remote is at the host (repository, open issues and pull or merge requests, open one from the branch in a terminal, clone URL), the repository chip, the New-folder clone option | a `ForgeProvider`: the host, the CLI, how a remote URL reads, the pages, the issue and request lists, the clone URL |
+| Container runtimes (`docker`, `lando`, `docksal`, `podman`, `kubernetes`) | `@webship.co/workspace-container` — `registerContainer(api, runtime)` | the row menu on every project the runtime recognises (its verbs as terminal sessions in the project, grouped, with the site link), the up/down caption answered after the row is drawn, the New-folder init option | a `ContainerRuntime`: how a folder is detected as a project, the CLI, how to tell whether it is up, the verbs and their commands |
+
+`@webship.co/workspace-upsun` 2.0.0 is the reference provider: `register(api)` is one line, the facts are
+in `src/lib/provider.ts`, and the bash tool, compose file, host install, settings template and theme
+are what the installer places.
+
+## The reference plugin
+
+`plugins/workspace-notes/` is the working example: a Notes rail button per enabled workspace,
+editing `NOTES.md` in the workspace folder through the modal, saved by a namespaced action.

package/README.md

@@ -1,3 +1,380 @@
-# Temporary Holding Version
+# workspace-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The **workspace** web dashboard — a visual UI + AI assistant for this tooling,
+served at **https://workspace.ddev.site** through DDEV.
+
+Basic Node.js (`node:http`, no framework) + [HTMX](https://htmx.org) (vendored
+in `public/htmx.min.js`). All pages are server-rendered; interactions swap in
+HTML fragments. Destructive actions ask in one shared confirm dialog — Wait!
+Are you sure you want to proceed with this action? — and fire on its Yes alone.
+
+## What version is this machine on?
+
+The toolbar says, beside the product name, and `core/workspace-app/scripts/update.sh --check`
+says the same thing. Both read **`core/workspace-app/.app-version`**, a file holding a tag and
+nothing else.
+
+It is written by all three things that install this tree, which is the point:
+
+| | writes the stamp |
+| --- | --- |
+| `core/scripts/install.sh` | the latest release tag, read from the repository |
+| `core/scripts/sync-tooling.sh --pull` | the tag the clone is sitting on |
+| `core/workspace-app/scripts/update.sh` | the tag it just installed |
+
+Before that only the **updater** wrote it, so a machine installed any other way answered
+`Installed: (untracked)` and was told an update was available to the version it already had —
+for ever. With one person that is a curiosity; across a team it is the support question nobody
+can answer, and an update prompt everyone learns to ignore.
+
+**When it cannot be told, it says so** — `version unknown` in the toolbar, with the three
+commands that would set it in the tooltip. A wrong version is worse than an absent one, because
+it stops the question being asked.
+
+`package.json`'s `"version"` is **not** it. That is npm metadata for an app that is never
+published, it has said `1.0.0` since the first commit, and a unit test fails if anything starts
+displaying it.
+
+## One `ddev start` at a time
+
+Every router-mutating verb — `start`, `stop`, `restart`, `poweroff`, `delete` — tears down the
+**one shared** `ddev-router` and rebuilds it with the routes of whatever is running. Two at once
+race on a single container, and the loser can leave it removed: every `*.ddev.site` address dies,
+the hub included, with healthy web containers behind it, and DDEV then refuses to start anything
+until `ddev poweroff`. Five clicks in thirty-eight seconds did exactly that.
+
+`core/scripts/ddev-shim/ddev` is a wrapper that holds a lock for those five verbs and `exec`s the
+real binary for everything else. It is **first on PATH inside the dashboard's container**
+(`/usr/local/sbin` precedes `/usr/local/bin`), so it covers the assistant's Bash calls, the
+`cmd-*.sh` scripts, the Web IDE's terminals and anyone in `ddev ssh` — not just the buttons.
+`install.sh` offers the same file on the host, where it needs root.
+
+Four rules it lives by, because a wrong wrapper breaks *every* `ddev` call including the
+dashboard's own twenty-second status reads:
+
+1. the real binary is found by **absolute path** and checked not to be the wrapper — resolving
+   through PATH would find the wrapper again and fork for ever;
+2. anything that is not a router verb is `exec`'d with **no lock and no subshell** —
+   `ddev list --json-output` costs what it always cost, and read-only verbs still run in parallel;
+3. **nothing is fatal** — a missing `flock`, an uncreatable lock file, and it says so once and runs
+   the command anyway, because refusing to run `ddev` is worse than the fault being prevented;
+4. it **never re-locks a lock already held**. The dashboard wraps its own calls, and taking the same
+   lock from inside deadlocks for the full 1800s timeout — proven by experiment before
+   `DDEV_ROUTER_LOCK_HELD` existed. Whoever holds the lock sets it; the wrapper exports it onward.
+
+The shim exists twice, because Docker cannot `COPY` from outside its build context:
+`core/scripts/ddev-shim/ddev` is the source, `.ddev/web-build/ddev-shim-ddev` is the copy the image
+takes, and a unit test fails if they differ.
+
+## The Web IDE (code-server)
+
+Every project row carries a **Codebase** menu, right after SCREENS, and every document
+workspace (`docs`, `worklogs`, `specs`, the `ai-*` folders) carries a **Files** one. Both offer
+the same three destinations, and the split is the point — it is GitLab's, and it is what stops
+a link that silently does nothing:
+
+| | opens | needs |
+| --- | --- | --- |
+| **Web IDE** | VS Code in the browser, at `https://ide.<hub_domain>/?folder=<path>` | nothing — works from any device |
+| **Visual Studio Code** | `vscode://file<path>` — the VS Code on the machine the *browser* is running on | the `vscode://` handler, which VS Code registers on install |
+| **IntelliJ IDEA** | `jetbrains://idea/open?file=<path>` — likewise, IDEA on that machine | the JetBrains Toolbox URL handler |
+| **Copy the path** | the path, for `code <path>` or `idea <path>` in a terminal | nothing |
+
+**It is code-server, pinned, on its own hostname.** `4.135.0` is baked into
+`.ddev/web-build/Dockerfile.workspace-app` from the standalone tarball — pinned because an
+editor that changes under people between image rebuilds is a support question nobody can
+answer. It runs as a `web_extra_daemon` bound to **127.0.0.1:8443**, and
+`.ddev/nginx_full/nginx-site.conf` proxies `ide.workspace.ddev.site` to it. Loopback plus that
+one vhost is the whole access control.
+
+A **hostname, not a subpath**: code-server is a single-page app that builds absolute URLs for
+its workers, its websocket and its static assets, and upstream's guidance is a dedicated
+(sub)domain. It costs nothing here — `*.workspace` is already in `additional_hostnames`, so
+DDEV's router routes it and the project certificate already covers it. The vhost uses an
+**exact** `server_name` so it wins over the regex block that sends everything else to the Node
+app, and carries the websocket `Upgrade`/`Connection` headers plus long read timeouts —
+without those the editor loads and then hangs "reconnecting…", because the terminal, the
+extension host and the file watcher are all websockets.
+
+**Its state lives in the workspace tree**, at `.code-server/` (gitignored): settings,
+keybindings and installed extensions survive an image rebuild, which they would not if they
+sat in the container.
+
+**When it is down the menu says so** rather than offering a dead link — a cached loopback
+probe, warmed at boot so the first render after a restart already knows. The note names the
+fix: `ddev restart`, or `docker exec ddev-workspace-web supervisorctl status`.
+
+### What makes it work — the actual options
+
+**Serving it** (`scripts/code-server-start.sh`, run as a `web_extra_daemon`):
+
+| flag | why |
+| --- | --- |
+| `--bind-addr 127.0.0.1:8443` | loopback only; the `ide.*` vhost is the whole access control |
+| `--auth none` | see the security note below — not a casual choice |
+| `--user-data-dir`, `--extensions-dir` under `.code-server/` | settings and extensions survive an image rebuild |
+| `--disable-telemetry`, `--disable-update-check` | nothing phones home; the version is pinned in the image |
+| `--app-name 'Webship Workspace IDE'` | the title bar and welcome page say where you are |
+
+**Nginx**, in `.ddev/nginx_full/nginx-site.conf`: an **exact** `server_name ide.workspace.ddev.site`
+(beats the regex block that routes everything else to the Node app), `proxy_set_header Upgrade` +
+`Connection $connection_upgrade` with a `map` for it, `proxy_read_timeout 86400s`,
+`proxy_buffering off`, `client_max_body_size 0`. The websocket headers are not optional: the
+terminal, the extension host and the file watcher are all websockets, and without them the editor
+loads and then hangs *reconnecting…*.
+
+**Editor settings**, seeded once into `.code-server/data/User/settings.json` (never overwritten, so
+your own changes stick):
+
+| setting | why |
+| --- | --- |
+| `security.workspace.trust.enabled: false` | VS Code opens every folder in **Restricted Mode** and refuses to start a terminal until you answer *"Do you trust the authors…"*. That prompt is for code you downloaded; here every folder is a project on this machine, opened from a dashboard that already offers a shell |
+| `terminal.integrated.profiles.linux` → **Claude Code**, **Claude Code (accept edits)** | the terminal dropdown offers them by name, so agents and skills are one click away instead of requiring you to know to type `claude` |
+| `files.associations` → `.module`, `.install`, `.theme`, `.profile`, `.engine`, `.inc` as PHP | without it the editor treats the files a Drupal developer opens most as plain text: no highlighting, no outline |
+| `files.exclude` / `search.exclude` → `node_modules`, `vendor`, `web/core`, `web/modules/contrib` | a Drupal site is ~21,000 PHP files of which almost none are yours; search is useless otherwise |
+| `files.watcherExclude` → the same trees plus `.git/objects`, `graphify-out`, `.ddev` | **one** built Drupal project is ~21,000 directories, 11,800 of them in those three trees, against a kernel limit of 65,536 watches **shared across the machine**. Without this, two open projects and the editor reports *Unable to watch for file changes* and silently stops noticing edits made outside it — a `composer install`, a `git checkout`, an agent |
+| `extensions.autoUpdate: "off"` | the same reason code-server is pinned |
+| `workbench.startupEditor: "none"`, `update.mode: "none"`, `telemetry.telemetryLevel: "off"` | no welcome page, no update nag, no telemetry |
+
+### Claude Code is in the editor, when it is configured
+
+The official extension (**`Anthropic.claude-code`**, on Open VSX — which is the registry
+code-server queries, so no marketplace switch and no `.vsix` juggling) is installed by
+`scripts/code-server-start.sh` on first start, and appears in the activity bar with its own
+chat (`Ctrl+Alt+I`).
+
+**Gated on Claude Code being usable here**, which means two things: the `claude` CLI on PATH, and
+a credentials file in `~/.claude` (the container bind-mounts it from the host). On a machine where
+Claude Code has never been logged in, installing it would put a panel in the editor whose only
+behaviour is to ask for a login that belongs on the host — so there the IDE keeps the terminal
+profiles and nothing else, and the script says so. Log in on the host with `claude`, then
+`ddev restart`.
+
+Installed **once**, when missing, with a timeout, and never fatally: an editor that will not start
+because a registry was slow is worse than an editor without one extension. `extensions.autoUpdate`
+is `"off"` for the same reason the code-server version is pinned.
+
+### Agents and skills are already loaded
+
+Nothing to install per project. The IDE runs **inside the dashboard's container**, which bind-mounts
+`~/.claude` — so a terminal there has the `claude` CLI with the **same agents, skills and commands as
+a session on the host** (86 / 42 / 6 on this machine), and Claude Code reads `CLAUDE.md` and
+`AGENTS.md` from the working directory upwards, so the folder's own rules apply automatically.
+
+In the IDE: **Terminal → new terminal dropdown → Claude Code**. Or type `claude` in any terminal.
+Inside it, `@` and `/` list the same items the dashboard's assistant offers, because they are the
+same files.
+
+**For local VS Code / IntelliJ** (the other two entries in the menu) nothing is configured — they
+open the folder on your own machine, with your own settings and your own extensions. Agents and
+skills come from your own `~/.claude` there, which is the point of that split.
+
+### Security posture, stated plainly
+
+**This dashboard has no authentication, and that is only safe because it is loopback-only.**
+It runs shell commands, serves an interactive terminal at `/terminal/<session>`, and a Web IDE
+with write access to the whole tree and a terminal of its own — in a container that mounts the
+Docker socket and the DDEV registry. Anyone who can reach the port has all of it.
+
+What keeps that acceptable is that nothing is reachable from the network: DDEV's router binds
+`127.0.0.1` (`router_bind_all_interfaces: false`, its default) and the machine answers nothing
+on its LAN address.
+
+**Two settings end that**, and both get changed for a good-looking reason:
+
+| setting | why someone changes it |
+| --- | --- |
+| `router_bind_all_interfaces: true` | DDEV documents it for Let's Encrypt, and for reaching a project from a phone |
+| `hub_domain: <a public domain>` | this README says the same system runs as a remote hub |
+
+So both are watched for, in the two places a person will be:
+
+- **`install.sh --check`** prints `✓ exposure loopback only` or a block naming the setting that
+  changed and what is reachable because of it;
+- **the dashboard itself** shows a banner on every page, not dismissible, because the person who
+  flips that setting a month later is not running the installer.
+
+If the hub is ever put on a public domain, the dashboard **and** the IDE need real
+authentication in front of them. One decision, not two.
+
+### Other things the security pass fixed
+
+- `core/config/settings.yml` (real API keys) and `.screens/.runner-token` (the screen runner's
+  entire access control) were **world-readable at `775`** while the CLI-managed secrets beside
+  them were correctly `600`. Both are `600` now.
+- One **high-severity** dependency advisory (`js-yaml`, exponential parsing → DoS) — fixed.
+- Security headers were set at **three** `writeHead` sites out of fifty-six, so every page but
+  the graph viewer went without. They are set once in the request handler now: `nosniff`,
+  `no-referrer`, `SAMEORIGIN`.
+
+### The IDE’s own posture
+
+`--auth none`. The dashboard has no login of its own until Sign in with Google (`auth.google`) is
+turned on, and it already serves a real interactive terminal at `/terminal/<session>`, so a second
+password in front of one door would be theatre.
+What this means concretely: **anyone who can reach the dashboard's origin can edit any file in
+`~/workspace` and run commands in that container**, which has the Docker socket and the DDEV
+registry mounted.
+
+That is acceptable for a local tool on `*.ddev.site` and **not** acceptable on a public
+`hub_domain`. If the hub is ever put on a public domain, the IDE *and* the dashboard need real
+authentication in front of them — the same decision, not two.
+
+## What it does
+
+- **Home** (`/`): the workspace cards grid — one card per folder in
+  `core/config/settings.yml`'s `workspaces:` list (read live, so adding a
+  workspace there shows up without code changes), with live project counts.
+- **Per-workspace pages** (`/dev`, `/test`, `/demos`, …): each workspace's own
+  project list with per-project **Backup / Filemode / Remove** actions, plus a
+  **Build** form listing that folder's `cmd-*-project.sh` builder scripts.
+- **AI Assistant** on every page (inline on home, floating 🤖 widget on
+  workspace pages): quick actions (New Drupal 11, New Webship, Status) and a
+  free-text chat backed by the local `claude` CLI in restricted, tool-free
+  print mode.
+- All actions run the real `cmd-*.sh` scripts (and `ddev`) against
+  `~/workspace` — this is a control panel, not a mock.
+
+## Setup
+
+You need the workspace files and DDEV. The quickest way to the files is the ZIP — no git, no
+clone: on [github.com/webship/workspace](https://github.com/webship/workspace) switch to the `1.0.x`
+branch, press **Code ▾ → Download ZIP**, unzip it and rename the folder to `~/workspace` (the full
+walkthrough, and two other ways, are in the [root README](docs/REFERENCE.md#get-started)).
+
+Then, once:
+
+```bash
+cd ~/workspace/core/workspace-app
+ddev start
+```
+
+Then open https://workspace.ddev.site. Everything else — building, starting, stopping, backing up,
+restoring and removing projects — can be done from there without another command.
+
+### How it runs
+
+The Node app runs **inside** the DDEV web container as a `web_extra_daemon`,
+with Docker-outside-of-Docker so it can manage sibling DDEV projects:
+
+- `.ddev/docker-compose.dood.yaml` bind-mounts the host's
+  `/var/run/docker.sock` and your `~/workspace` tree (at the same absolute
+  path, via `${HOME}` interpolation).
+- `.ddev/web-build/Dockerfile.workspace-app` installs the `docker` CLI and the
+  `ddev` binary in the web image, and aligns the container's `docker` group
+  GID with the host's.
+- `.ddev/nginx_full/nginx-site.conf` proxies the site to the app on
+  `127.0.0.1:3000` inside the container.
+
+### Per-machine adjustments
+
+- **docker group GID — handled for you.** The container has to share this
+  host's docker GID or every `ddev` command inside it fails with a permission
+  error, and the symptom is a dashboard where every project reads as Stopped
+  forever while running perfectly well. Two files carry the number: the
+  `groupmod`/`usermod` line in `.ddev/web-build/Dockerfile.workspace-app`
+  (which is what `sg docker` in the supervisord command resolves) and
+  `group_add` in `.ddev/docker-compose.dood.yaml` (which is what actually puts
+  the running process in the group — DDEV pins `user: 1000:1000`, so a
+  build-time `usermod` never reaches it).
+
+  `core/scripts/docker-gid.sh` writes both from the host's socket.
+  `core/scripts/install.sh` runs it at setup and reports it in its survey, and
+  `core/scripts/sync-tooling.sh` runs it **after** mirroring — this directory is
+  mirrored wholesale, so a hand edit would be overwritten by the next `--pull`.
+  Check it any time:
+
+  ```
+  bash core/scripts/docker-gid.sh --check
+  ```
+- **The DDEV project registry** (`~/.ddev`) is bind-mounted in, so `ddev list`
+  in here sees the same projects as the host. Without it the container has its
+  own empty registry and reports one project — itself — which produces the same
+  "everything is Stopped" symptom by a different route.
+- **Bind-mounted host paths are a trap Docker sets.** A bind mount whose source
+  does not exist is *created* — as a directory, owned by root. Every optional tool
+  the dashboard shares from the host is such a source, so on a machine without
+  `twg` the first start used to create `~/.local/bin/twg` **and `~/.local/bin`**
+  as root: the JIRA button then never appeared however complete `jira:` was, and
+  nothing could install a user binary there any more, including the
+  `drupal-ci-local` wrapper the GitLab CI green-gate writes.
+
+  `core/scripts/host-mounts.sh` creates each of those paths as you before Docker
+  can, and comments the `twg` volume out of `.ddev/docker-compose.twg.yaml` while
+  `twg` is not installed — restoring it the moment it is. It runs from the
+  project's own `pre-start` hook and from `install.sh`. `--check` reports without
+  changing anything, and it names the paths only root can hand back.
+- **Jira** needs the Teamwork Graph CLI on the host:
+  [teamworkgraph.com/cli](https://teamworkgraph.com/cli) ·
+  [developer.atlassian.com/cloud/twg-cli](https://developer.atlassian.com/cloud/twg-cli/)
+  ```
+  curl -fsSL --retry 2 https://teamwork-graph.atlassian.com/cli/install | bash
+  ~/.local/bin/twg doctor
+  ```
+  It is mounted in rather than installed in the image: one binary, one OAuth
+  session, and `twg login` on the host reaches the container instantly. When it is
+  absent the JIRA button renders **disabled**, with the reason in its tooltip,
+  rather than vanishing.
+- **Upsun** needs its CLI on the host, mounted in the same way and for the same
+  reason as `twg` — one binary, one session:
+  [developer.upsun.com/cli](https://developer.upsun.com/cli)
+
+  Upsun's own installer sets up an apt repository, so it needs root and an
+  interactive password; in a pipe it fails with *"sudo: A terminal is required to
+  authenticate"*. `install.sh` therefore prefers the **release tarball** — one
+  static binary into `~/.local/bin`, no root at all — and falls back to the
+  official installer only if GitHub is unreachable:
+
+  ```
+  ver=$(wget -qO- https://api.github.com/repos/upsun/cli/releases/latest \
+        | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p' | head -1)
+  wget -qO- https://github.com/upsun/cli/releases/download/v$ver/upsun_${ver}_linux_amd64.tar.gz \
+    | tar -xz -C /tmp upsun && install -m 0755 /tmp/upsun ~/.local/bin/upsun
+  upsun login          # browser OAuth; writes SSH certificates
+  ```
+
+  **The dashboard needs its own credential, and this is not optional.** `upsun login`
+  writes a session into the host keyring, and a container cannot reach a keyring — so
+  every UPSUN action in the dashboard (the environment list, the live URLs, *Get
+  database & files*) authenticates with an API **token** instead:
+
+  ```yaml
+  # core/config/settings.yml
+  upsun:
+    cli_token: …        # Upsun console → My profile → API tokens
+  ```
+
+  `upsunJobEnv()` injects it as `UPSUN_CLI_TOKEN` for each CLI call. Without it the
+  actions answer *"No Upsun API token configured"*; with the wrong **kind** of token
+  they answer *"The request could not be authorized. Unable to authenticate the
+  provided API token"* — which reads like an expiry. An **Atlassian** token in that
+  field, recognisable because they start `ATATT`, produces exactly that message.
+  `bash core/scripts/install.sh --check` reports the field by shape, never its value.
+
+  Two related details worth keeping:
+
+  - **The CLI prints the reason FIRST and a usage synopsis LAST.** These errors are
+    rendered through `cliError()` in `format.js`, which drops the synopsis and keeps
+    the head — a tail slice showed a list of flags and threw the reason away.
+  - **It hard-wraps mid-word.** The real output is `provided AP` / newline / `I token.`,
+    so matching its text has to survive the wrap; the check in `actions/upsun.js` does.
+- **Chat**: the assistant chat shells out to the `claude` CLI **inside the
+  container** (installed in the web image via `npm install -g
+  @anthropic-ai/claude-code`); it authenticates through your host's
+  `~/.claude` + `~/.claude.json`, which are bind-mounted in. If you've never
+  logged in to Claude Code on the host, run `claude` there once first.
+- **Voice input**: the mic button uses the browser's Web Speech API
+  (Chrome/Edge; hidden automatically on browsers without support).
+
+## Security note
+
+This app executes shell scripts with real side effects (build, backup,
+**delete**) and has host-Docker access. The AI assistant runs in **agent
+mode**: its `claude -p` calls are allowed Bash/Read/Glob/Grep inside the
+container (Write/Edit stay disallowed, and its instructions forbid deleting
+anything unasked), so a chat message can really build, start, stop, back up
+and open projects — and steer the page afterwards via NAVIGATE/OPEN/REFRESH
+directives. Every action and chat message is appended to `actions.log`.
+It binds only to the DDEV-internal port and is meant for local development
+machines — do not expose `workspace.ddev.site` beyond localhost without
+adding authentication.