mirror of
https://github.com/Matysh/houseplan-card
synced 2026-10-03 05:08:53 +00:00
docs(security): убрать доступы к стенду и домашнему HA из публичных документов (#677)
Волна 0 эпика #674. В публичном дереве лежали логин и пароль закрытого dev-стенда (TESTING-DEMO.md), карта доступа к домашнему инстансу и стенду — хост, порт SSH, имена ключей, IP, пути конфигурации, место хранения PAT (STATUS.md, DEVELOPMENT.md). TESTING-DEMO.md: строка про dev-стенд без учётных данных. STATUS.md: строка «Home instance» удалена целиком, из строк «GitHub» и «Demo stand» убраны ключ, PAT, хост и заметка памяти — публичные адреса и описание стенда остались. DEVELOPMENT.md: разделы «Deployment to the dacha» (ещё и противоречил PROCESS.md §12 — ручное копирование запрещено) и «Production objects in HA» удалены; вместо первого — три строки «Deployment» о HACS по тегу; раздел «Environment (cowork sessions)» удалён вместе с ними — три его пункта из шести называли тот же ключ, PAT и хост (в эпике он значился за волной 3). Строки остаются в истории git, поэтому пароль стенда меняет владелец — отдельным подтверждением в задаче. Issue: #677 User-Visible: no Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018qZfe7YS4rqEMKoVeS3GKd
This commit is contained in:
+4
-55
@@ -20,25 +20,6 @@ Existing touch editor behaviour is not silently disposable: when changing a
|
||||
covered workflow, update its test and documentation explicitly and record why
|
||||
the degradation is accepted.
|
||||
|
||||
## Environment (cowork sessions)
|
||||
|
||||
- The source of truth is **GitHub `main`** (https://github.com/Matysh/houseplan-card).
|
||||
In a sandbox session restore from it or from `houseplan-card.git.bundle`
|
||||
(`git clone houseplan-card.git.bundle hpcN` into a **fresh** /tmp directory).
|
||||
- The user's folder `houseplan/houseplan-card/` is a file mirror (synced after every commit)
|
||||
+ an up-to-date `houseplan-card.git.bundle`. The mount cannot delete files — stale
|
||||
artifacts linger there; git is authoritative.
|
||||
- `/tmp` persists between sessions, **but files created in previous sessions belong to
|
||||
`nobody` and are unreadable** (this hit `/tmp/hpc`, `/tmp/ha_jb`, `/tmp/shots/srv`).
|
||||
Always clone into a new directory and re-run `npm ci`; ask the user to re-upload `ha_jb`.
|
||||
- Headless Chromium for smoke tests: `PLAYWRIGHT_BROWSERS_PATH=/tmp/pw npx playwright
|
||||
install chromium-headless-shell`, then run with `LD_LIBRARY_PATH` pointing to the
|
||||
extracted lib dirs (`libs/lib/x86_64-linux-gnu:libs/usr/lib/x86_64-linux-gnu:.../nss`).
|
||||
- Restart HA over SSH with `nohup ha core restart >/dev/null 2>&1 </dev/null &` —
|
||||
a plain `ha core restart` holds the SSH session until the sandbox call times out.
|
||||
- GitHub pushes: classic PAT (repo+workflow scopes), created via the user's Chrome;
|
||||
stored in `~/.git-credentials` for the session.
|
||||
|
||||
## Local contour in 5 minutes (локальный контур за 5 минут, #633)
|
||||
|
||||
Three commands take a fresh Linux sandbox (agent session, WSL, a clean VM) from
|
||||
@@ -347,35 +328,11 @@ npm run bundle:release # candidate only: also → custom_components/housep
|
||||
node scripts/bundle-tree.mjs dist custom_components/houseplan/frontend # candidate parity
|
||||
```
|
||||
|
||||
## Deployment to the dacha (ha.jbstudio.pro)
|
||||
## Deployment
|
||||
|
||||
- SSH: port **22222**, root, key `ha_jb` (lives in the user folder `houseplan/.secrets/ha_jb`,
|
||||
outside git; copy into the sandbox with chmod 600 — only ask the user if it is gone).
|
||||
- **The HA config root is `/mnt/data/supervisor/homeassistant`** — in this SSH
|
||||
environment `/config` does not exist; a deploy aimed at `/config/...` fails
|
||||
with "No such file or directory".
|
||||
- Frontend: copy the complete `custom_components/houseplan/frontend/` tree.
|
||||
Copying only `houseplan-card.js` is unsupported: the entry imports hashed chunks and
|
||||
validates its editor runtime against the build fingerprint.
|
||||
- Cache busting: `sed` the `?v=` version in `.storage/lovelace_resources`, then restart HA.
|
||||
- **The `frontend/` subfolder is not optional.** `__init__.py` registers
|
||||
`Path(__file__).parent / "frontend" / "houseplan-card.js"` as the static path.
|
||||
A copy dropped next to `__init__.py` (…/houseplan/houseplan-card.js) is served
|
||||
by nobody: md5 on the server matches, the browser still gets the old bundle,
|
||||
and hours go into debugging a bug that was already fixed. Cost this mistake
|
||||
once: 2026-07-27, two releases deployed into the void.
|
||||
- The whole integration: tar c custom_components/houseplan (--exclude __pycache__) → tar x on the server.
|
||||
- **Verification is mandatory, and it must go over HTTP** — comparing md5 against
|
||||
the file you just copied proves nothing about what the browser receives. The
|
||||
one check that counts:
|
||||
`curl -s https://ha.jbstudio.pro/houseplan_files/houseplan-card.js | grep -o '1\.[0-9]*\.[0-9]*' | sort -u`
|
||||
must print the version just built. (Inside the SSH add-on `localhost` is NOT
|
||||
HA — use the host `homeassistant`.)
|
||||
- Python changes require an HA restart (`ha core restart`, holds the connection until it finishes, HTTP
|
||||
comes back up in 1–3 min). JS changes — just a page refresh (the static path is served
|
||||
with no-cache).
|
||||
- After deploying JS — check in the browser (Ctrl+F5) and the console (there must be no errors from
|
||||
houseplan-card.js; a broken bundle takes down all dashboards).
|
||||
Installations update themselves through HACS by release tag (`PROCESS.md` §12: no
|
||||
manual copying into a running Home Assistant); the closed dev stand auto-deploys
|
||||
the `dev` branch. Access to the owner's instances is not documented here.
|
||||
|
||||
## Frontend cache and the "empty view"
|
||||
|
||||
@@ -763,14 +720,6 @@ emergency hotfix, and document the exception in the handoff.
|
||||
history and docs/ARCHITECTURE.md (SVG→base-space transforms: f1 0.647/(490,27), f2 0.896/(351,21)).
|
||||
- Room fitting: render the plan with rectangles overlaid (cv2) → snap to walls → manual fine-tuning.
|
||||
|
||||
## Production objects in HA (the dacha)
|
||||
|
||||
- Dashboard `plan-doma`, panel view, card `custom:houseplan-card` (icon_size 2.5).
|
||||
- The houseplan integration: entry loaded, `.storage/houseplan.layout` — the layout (server-side).
|
||||
- The old prototype `/config/www/houseplan/` (iframe) is kept as a fallback, do not touch.
|
||||
- configuration.yaml backups: `.bak-avgtemp` (before the average-temperature sensor edit).
|
||||
|
||||
|
||||
## Smoke tests (since 2026-07-27)
|
||||
|
||||
Every `demo/smoke_*.mjs` ends with:
|
||||
|
||||
+2
-3
@@ -42,17 +42,16 @@ same commit as the change it describes.
|
||||
| Current local cycle | **Beta v1.78.0-beta.5 candidate** — refreshed on the exact integrated `dev` tree after all eleven S8 items landed. It adds configurable straight and spiral stairs with optional one-way floor navigation (#663), keeps the 2.5D room metrics row at the flat-plan distance from the name at every zoom (#665), puts the active editor's close cross inside the highlighted tab (#666), makes the static space card fully inert again (#664), and aligns the maintained documentation with the current code and process canon (#667). The refresh also carries internal work: floors with the maximum stair count no longer subtract every stair from each room's clean-floor area on load (#669), the review index knows stable release reviews (#670), the Validate input manifest covers `assets/` and ignores harness READMEs (#671, #672), the five Stage 6 acceptance scenes join the golden matrix (#673), and the isometric `spaceSwitchMs` ceiling is recalibrated to the 2.5D runner level (#675). `main` remains on stable v1.77.0. |
|
||||
| 2.5D View | #89 Stage 1 ships in v1.63.0-beta.1, #122 Stage 2 in v1.64.0, #160 Stage 3 in v1.73.0-beta.1, #570/#583 Stage 4 on `dev`. #649 Stage 6 makes it public: the installation-wide General settings switch `settings.volumetric_view` (Display, third item) replaces the alpha entry, the header toggle and the phone-menu item; raised tiles with one floor-shadow layer, a soft sun wash instead of Flat wedges, user wall colours independent of the theme, furniture at the Flat line width. #651 keeps device/lock clusters rigid and independent of live zoom/pan. Flat remains default and byte-for-byte unchanged; editors and `houseplan-space-card` stay Flat. Acceptance frames: `docs/design/649-25d-stage6/ACCEPTANCE.md`. |
|
||||
| Workflow | Superseded 2026-08-12: the pre-1.62 rule of "local edits without tests or commits" is **dead** — since release 1.62 every product change follows `PROCESS.md` (issue in `S5-ready`+, branch `issue/<NN>-slug`, trailers on every commit, review pipeline; `AGENTS.md` is the summary). Release mechanics below remain current. A requested pre-release gets a production build plus the smallest targeted unit/smoke set covering the changed surfaces, one tested `dev` commit/tag and a GitHub Release with `prerelease=true`; `main` stays untouched. The complete local frontend/backend/smoke gate runs only before a stable release, after which `main` is fast-forwarded to the exact tested `dev` SHA and the stable release is produced by `release.yml` (`workflow_dispatch` on `main` with the tag) — the only publisher of installable assets since #540: gates on the exact SHA (Validate, Full Performance, E2E on the candidate commit), one build, `houseplan.zip` archived from the committed tree, `SHA256SUMS`, draft → publish → read-back verification; a release published by hand in the GitHub form is turned back into a draft and walked through the same path, and a re-dispatch on a public tag is a repair that adds only missing assets. Release bodies are short and bilingual (Russian first); every bullet links its GitHub issue (#NN) so the #328 rules stay machine-checkable. A STABLE body aggregates the changelog since the PREVIOUS STABLE release (never since the last beta): features/fixes described across the line's beta changelogs must appear, while bugs that were introduced and fixed strictly inside the beta line (never shipped in any stable) are excluded — draft with `npm run release:notes -- <tag>`, curate by hand, then `npm run release:notes -- <tag> --verify` must pass. `Мелкие исправления и улучшения` / `Small fixes and improvements` is allowed only when the range really contains user-visible work not itemised in the body; a single-issue hotfix ships without it (the verifier enforces this). Every body ends with separate links to the Russian and English changelogs. Open or partially delivered issues are never presented as shipped. Telegram announcements are sent only for stable releases; beta and RC publication is silent. `docs/RELEASE-NOTES.md` is the current canonical body instance; `npm run release:prerelease -- <tag> --issues=… --yes` is the primary local publication path and the manual `Publish prerelease` workflow is its GitHub-only equivalent once present on `main`. Nothing is copied to the home instance by hand |
|
||||
| GitHub | https://github.com/Matysh/houseplan-card — [Issues](https://github.com/Matysh/houseplan-card/issues) are the canonical task records; their labels carry priority and workflow status (`PROCESS.md` §9). GitHub Projects is no longer used. `main` carries stable releases; pre-release tags may point directly at `dev`. Work lands on `dev` and is merged into `main` for a stable release, so `dev` is normally equal to or ahead of `main`, never behind. Push via SSH key `ha_jb` (remote git@github.com:…); API releases via the fine-grained PAT in `~/.git-credentials` (Contents R/W, issued 2026-07-23) |
|
||||
| GitHub | https://github.com/Matysh/houseplan-card — [Issues](https://github.com/Matysh/houseplan-card/issues) are the canonical task records; their labels carry priority and workflow status (`PROCESS.md` §9). GitHub Projects is no longer used. `main` carries stable releases; pre-release tags may point directly at `dev`. Work lands on `dev` and is merged into `main` for a stable release, so `dev` is normally equal to or ahead of `main`, never behind. |
|
||||
| CI | #541 replaces three incompatible meanings of “green” with one machine-verifiable Validate proof: candidate SHA/tree, run ID/attempt, requested checks, actually executed jobs and independently checked content-addressed reuse. Review, merge and release share the same closed state machine; a light green dispatch cannot hide a full red run, and a dispatch without six executed mutant jobs cannot authorize review or merge. #656 makes repeated release proofs fail closed: among compatible full runs on one SHA the newest decides, so a later full red blocks an older green while light, stale and cancelled runs are skipped. #573 makes the proof composite — product-tree identity, accepted golden overlay (tree, index hash, either a `Baseline-Reviewed` run or a `Baseline-Reviewed-Local` attestation) and the content key of every reusable job — and release consumers on the candidate checkout recompute and compare all of it; the accepted overlay is an input of `golden` only, so a baseline-only commit after a golden-red candidate reuses smoke, performance smoke, parity and backend, skips caught witnesses and re-runs golden alone. #641 permits a complete attested WSL/ext4 capture from a clean published SHA to replace the first expected-red artifact-transport run, while a full independent GitHub Validate on the accepted exact SHA remains mandatory. Prerelease publication requires a green full exact-SHA proof covering frontend/backend, smoke (including the #73 rAF frame sampler), golden, HACS/Hassfest and the short absolute-ceiling performance smoke. Obsolete same-ref Validate runs are cancelled. Full seven-sample base/candidate performance remains in `performance.yml` (`main` push excluding workflow/docs-only mirrors, weekly, manual); stable release assets fail closed unless Validate and Full Performance are green for the exact tagged SHA and the stable-only CDP compositor screencast finds no empty/black presented frame. |
|
||||
| Local toolchain | #557 removes ambient-PATH claims from the owner's workstation: `scripts/windows-toolchain.ps1` keeps verified portable repository-pinned Node and a dedicated repository-pinned Python `.venv-ci` without changing system defaults; `toolchain:check` reports the current versions and exact executable/package/browser paths. #576 verifies the actual owner setup end to end: repeated Windows setup reuses the existing Node/Python/Chromium, the pinned small gate and pure backend subset are green, and repeated WSL `--verify` runs from an ext4 clone pass the real HA subset without skips and produce a Linux golden capture. The WSL entrypoint uses its own nvm + `.venv-ci`. #641 adds `golden:wsl:capture`: only the ext4 clone, clean named branch at its published remote SHA, pinned toolchain, current source fingerprint, complete matrix and witness floor can produce the self-hashed local passport; plain local capture remains diagnostic. The passport can source baseline review, but exact-SHA Linux CI remains the merge/release canon. |
|
||||
| HACS | **In the default catalog since 2026-08-25** (hacs/default#9004 merged). Install = plain HACS search. `houseplan.zip` is attached to stable tags automatically (verified on v1.72.0); forum/4pda announcement still pending |
|
||||
| Home instance | ha.jbstudio.pro (SSH port **22222**, key `ha_jb`; HA config root is `/mnt/data/supervisor/homeassistant` — `/config` does NOT exist in this SSH environment), last direct copy was **v1.57.0**; from v1.58.0 on it updates itself through HACS by tag (no scp) |
|
||||
| Localization | UI en/ru/de (src/i18n/*.json), everything user-visible localized incl. kiosk popover; German is loaded lazily through the registry introduced by #62 |
|
||||
| Furniture | #159 replaces the flat ~30-item picker with a two-level category/variant palette; #593 raises it to 60 top-view symbols, all designer artwork. #606 derives corrected pack 0.4.1 from the reviewed 93-SVG MIT source pack 0.4.0: exercise is a visible category, bookshelf/shelf_floor art matches their names, and old cactus objects resolve without rewriting saved data. The active pack is `assets/furniture/houseplan-0.4.1`; plan art is lazy (#474), front-view menu art stays in the lazy editor graph, and saved geometry/default dimensions remain unchanged. |
|
||||
| Tests | Four layers: Node unit (`npm test`: frontend pure modules + tooling policy), pure backend (`pytest tests_backend`, runs anywhere), HA-harness backend (same folder, CI only — uses repository-pinned Python plus pytest-homeassistant-custom-component), and browser smokes (`demo/smoke_*.mjs`, headless chromium). **Counts and runtime pins are not duplicated here** — they drift faster than release prose; run `npm run inventory` for current counts and `npm run toolchain:check` for the executable pins, or read them from the exact CI run |
|
||||
| Input support | Owner's rule since 2026-08-08: View and kiosk are fully supported and release-blocking on touch. All three editors are desktop-first; touch editing is best effort and may be awkward, reduced or absent when parity is expensive. `docs/TOUCH-SUPPORT.md` defines the non-negotiable safety floor and documentation/test rules |
|
||||
| Vacuums | Live puck, server-side trails and fit calibration are shipped. The local v1.61 Stage 1 contract in docs/VACUUM.md adds explicit Dreame/XCME/Valetudo coverage, registry-less source selection, capability diagnostics, path-gap preservation and source-health warnings; #205 resumes one ended same-map run through an inclusive 30-minute station/pause grace. #209 renders current and previous trails through the same bounded 17.5 cm rounded-corner curve without changing stored points or gaps. Roomba remains Stage 2 |
|
||||
| Demo stand | **https://demo.houseplan.tech** — public, login `demo`/`demo`, resets to a pristine synthetic home every hour. **https://dev.houseplan.tech** — closed (basic auth), auto-deploys the `dev` branch every 10 min. Host: `ssh -i ~/.ssh/hp_stand hp@135.106.166.146`; layout, seeds and gotchas in the memory note `houseplan-demo-stand`. Since 2026-07-31 the stand covers most of the manual checklist: a scripted robot vacuum (`demo/stand/demo_robot` — Tasshack-shaped map sensor, serpentine run, pre-solved calibration, seeded server trail), Zigbee-style LQI template sensors, hand/auto-triggered leak+smoke alarms, an hvac_action climate marker and working script/scene/automation targets for tap-run. The stand-specific how-to-check guide is **docs/TESTING-DEMO.md** |
|
||||
| Demo stand | **https://demo.houseplan.tech** — public, login `demo`/`demo`, resets to a pristine synthetic home every hour. **https://dev.houseplan.tech** — closed (basic auth), auto-deploys the `dev` branch every 10 min. Since 2026-07-31 the stand covers most of the manual checklist: a scripted robot vacuum (`demo/stand/demo_robot` — Tasshack-shaped map sensor, serpentine run, pre-solved calibration, seeded server trail), Zigbee-style LQI template sensors, hand/auto-triggered leak+smoke alarms, an hvac_action climate marker and working script/scene/automation targets for tap-run. The stand-specific how-to-check guide is **docs/TESTING-DEMO.md** |
|
||||
| Community | **Telegram chat: https://t.me/ha_houseplan** (created 2026-07-27) — the primary user-facing support channel; GitHub issues stay for bugs/features. Link it from any new release notes and posts |
|
||||
| Product scope | `docs/SCOPE.md` is the feature guard rail; `docs/TOUCH-SUPPORT.md` is the input-support contract — check both before accepting interaction work |
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Чек-лист ручного тестирования на публичном демо-стенде
|
||||
|
||||
> **Стенд:** https://demo.houseplan.tech — вход **demo / demo** (админ).
|
||||
> Dev-версия: https://dev.houseplan.tech (basic auth `hp` / `houseplan-dev-2026`, дальше тот же demo/demo).
|
||||
> Dev-версия: https://dev.houseplan.tech — закрытый стенд (basic auth, доступ у владельца).
|
||||
>
|
||||
> **Стенд сбрасывается каждый час** к эталонному состоянию — это фича: ломайте
|
||||
> смело, удаляйте комнаты, заливайте планы, через час всё вернётся (обратный
|
||||
|
||||
Reference in New Issue
Block a user