From 625d8c2c0401b893dfd10b84cd115fd5e7fca74d Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Tue, 27 Oct 2026 14:55:02 +0000 Subject: [PATCH 01/19] docs: plan Telescope Vue 3 and shared Vite+ tooling Define two sequential PRs: migrate Telescope to Vue 3 using Horizon as the concrete coding reference, then consolidate framework JavaScript development under Vite+, pnpm workspaces, and dependency catalogs. Document component ownership, lifecycle cleanup, UI dependency changes, verified defects, and regression coverage for the dashboard migration. Preserve Laravel-compatible PHP APIs and recognizable upstream structure so future Telescope updates remain straightforward to port. Specify workspace membership, shared commands, dependency policy, CI verification, and advisory checks. Keep application skeletons independently installable and continue shipping committed framework assets through unchanged subtree splits. Include source references, implementation examples, browser checks, packaging verification, and performance safeguards. --- ...2026-10-27-telescope-vue3-and-vite-plus.md | 317 ++++++++++++++++++ 1 file changed, 317 insertions(+) create mode 100644 docs/plans/2026-10-27-telescope-vue3-and-vite-plus.md diff --git a/docs/plans/2026-10-27-telescope-vue3-and-vite-plus.md b/docs/plans/2026-10-27-telescope-vue3-and-vite-plus.md new file mode 100644 index 000000000..cd0e2118e --- /dev/null +++ b/docs/plans/2026-10-27-telescope-vue3-and-vite-plus.md @@ -0,0 +1,317 @@ +# Telescope Vue 3 and shared JavaScript tooling + +## Objective and delivery + +Modernize Telescope's dashboard using Horizon's actual Vue 3 conventions, then consolidate framework JavaScript development under Vite+, pnpm workspaces, and dependency catalogs. Deliver two independently reviewable PRs against `0.4`, in that order. Do not change `0.3` or `main`. + +Work in `/home/binaryfire/workspace/contrib/hypervel/components-vite-plus`. The initial branch is `chore/telescope-vue3`. After PR 1 merges, create PR 2's branch from updated `origin/0.4` in this worktree; do not mix the toolchain migration into PR 1. Commit whole files in focused commits with explanatory bodies. Commit, push, open, or merge PRs only when authorized; never squash by default. + +Read this plan, the monorepo root `CLAUDE.md`, and the worktree's `AGENTS.md` after compaction. This plan does not override their approval, verification, source-reading, or dependency-management requirements. No implementation is authorized merely by writing the plan. + +Remaining work: + +- Implement and verify Part 1, including its generated assets and documentation. +- After Part 1 merges, implement and verify Part 2. + +## Shared decisions + +- Keep Laravel-compatible PHP methods, signatures, named arguments, configuration, routes, payloads, authorization, and asset-publishing behavior. Any newly proposed public API departure needs the owner's approval under `AGENTS.md`; this plan assumes none. +- Use Horizon as the concrete frontend reference: Options API objects, component-local state and lifecycle hooks, ordinary Vue Router, explicit imports and component registration, readable methods, and Laravel-style method documentation. Retain Telescope's recognizable filenames, screen boundaries, and feature behavior so upstream changes remain easy to map. No Composition API rewrite, TypeScript conversion of the dashboard, generic UI framework, new state-management library, or permanent Vue compatibility mode. +- Churn is not a reason to retain defects, dead imports, obsolete configuration, or misleading comments. Equally, sharing tooling does not require replacing every library or forcing different supported major versions together. Investigate newly found problems and resolve them under the repository's approval rules. +- No extra request-time PHP work, asset compilation on application startup, network calls for frontend dependencies at runtime, or lazy asset downloads. Preserve polling frequency, cancellation, bounded work, and cleanup. Investigate any meaningful bundle or runtime regression before accepting it; benchmark only after confirming the machine is idle with the owner. +- `components` owns framework frontend development. Maintainers commit source, dependency/lockfile changes, and rebuilt distributable assets together. Subtree splitting copies those files unchanged; Composer consumers do not need Node, pnpm, Vite+, or the root catalog. +- Split repositories retain source but are not standalone frontend development environments after Part 2. Developers customizing them use a fork of `components`, or supply explicit versions and tooling in their own split fork. Do not add catalog-expansion code, synthetic split commits, a second lockfile generator, or a publishing build service. +- Keep application skeletons outside the framework dependency workspace. They retain complete manifests and independent builds after `composer create-project`. Do not create catalog references, parent-directory imports, or framework toolchain dependencies in their shipped files. Their config synchronization and installation workflows remain authoritative. +- No generic dependency updater, custom task scheduler, blanket peer-dependency bypass, broad lint suppression, or new mandatory Git hooks. Use native package-manager, Vite+, Vue, and existing framework facilities. + +## Verified starting points and references + +The paths below are relative to this worktree unless absolute. Read the actual source again before changing it; dependency versions must be checked against current releases and the existing release-age policy when implementation begins. + +| Area | Relevant files and constraints | +| --- | --- | +| Horizon reference | `src/horizon/resources/js/app.js`, `base.js`, `components/Alert.vue`, `components/Poll.vue`, and `screens/recentJobs/index.vue`: Vue 3, Router 4, Options API, native Bootstrap 5 APIs. Its style is a reference, not proof that every existing detail is correct. | +| Telescope | `src/telescope/resources/js/`, `resources/views/layout.blade.php`, `resources/sass/`, `vite.config.js`, `vitest.config.js`, `package.json`, `package-lock.json`: Vue 2.7, Router 3, Bootstrap 4, jQuery, Popper 1, Vue Test Utils 1. | +| Upstream | Read-only Laravel references under `/home/binaryfire/workspace/references/laravel/{telescope,horizon}`. Laravel Telescope currently remains on Vue 2. Compare source/tests and the established upstream tracking records; adapting a dashboard to Vue 3 does not change which upstream fixes need porting. | +| Root tooling | `package.json`, `pnpm-workspace.yaml`, `pnpm-lock.yaml`, `vitest.config.ts`, `tsconfig.json`: pnpm already exists; Horizon, Telescope, and Workbench are excluded. The nested exception renderer and AI workbench are not selected by `src/*`. | +| Existing CI | `.github/workflows/tests.yml` runs root MCP/Wayfinder tests and a separate npm installation/test for Telescope. `.github/workflows/skeletons.yml` builds a fresh base application separately. | +| Distribution | `bin/split.sh` splits committed trees, without rewriting manifests. Horizon/Telescope `dist/`, the renderer's `dist/`, Workbench's `public/build/`, and MCP's minified SDK are committed assets. | + +Primary research: + +- [Vue migration changes](https://v3-migration.vuejs.org/breaking-changes/), [Vue API styles](https://vuejs.org/guide/introduction.html#api-styles), and [Router migration](https://router.vuejs.org/guide/migration/): retain Options API while updating app initialization, router creation, slots, lifecycle hooks, and test render functions. +- [Bootstrap migration](https://getbootstrap.com/docs/5.3/migration/): native component APIs, namespaced data attributes, and changed utilities require corresponding template/Sass updates; changing the dependency alone is insufficient. +- [Vite+ monorepos](https://viteplus.dev/guide/monorepo), [migration rules](https://viteplus.dev/guide/migrate-rules), [tests](https://viteplus.dev/guide/test), and [CI](https://viteplus.dev/guide/ci): central quality configuration with package-local build/test configuration, exact toolchain pins, normal workspace task selection, and one setup action. +- [pnpm catalogs](https://pnpm.io/catalogs), [workspace settings](https://pnpm.io/settings), and [lockfile format](https://github.com/pnpm/pnpm/blob/main/pnpm/docs/lockfile.md): catalogs centralize versions, not dependency declarations. Catalog expansion happens during npm packaging, not Git splitting. pnpm 12 may write two YAML documents in one lockfile. +- [Oxc compatibility](https://oxc.rs/compatibility.html): Vue formatting and script linting do not imply Vue template linting. Vue compilation and behavioral tests remain necessary. +- [Dependabot catalogs](https://github.blog/changelog/2025-02-04-dependabot-now-supports-pnpm-workspace-catalogs-ga/), [supported ecosystems](https://docs.github.com/en/code-security/reference/supply-chain-security/supported-ecosystems-and-repositories), and [dependency graph limitations](https://docs.github.com/en/code-security/reference/supply-chain-security/dependency-graph-supported-package-ecosystems): version-update support and security-graph ingestion are separate capabilities. Do not assume a green Dependabot configuration proves transitive advisory coverage. + +## Part 1 — Telescope dashboard migration + +### 1. Establish the behavior and build baseline + +Read all Telescope frontend components, screens, mixins, Blade layout, styles, and existing query-preview tests. Compare Horizon's corresponding setup and frontend conventions before editing each area. Use current Laravel Telescope as the behavior reference, including fixes already present in Hypervel. + +Run the current Telescope tests and production build using its existing independent npm setup. Record expected asset filenames and raw/compressed sizes outside the repository. Exercise the existing UI sufficiently to distinguish migration failures from inherited defects. Source changes and verification for this PR stay in Telescope except for directly required CI/docs updates. + +Preserve these contracts: + +- `/telescope` and configured empty, root, or nested Telescope paths; route names, IDs, query strings, history navigation, and deep links. +- Existing API endpoints, request bodies, CSRF behavior, timezone formatting, recording toggles, clear confirmation, and auto-load local-storage preference. +- Lists, filtering, family grouping, pagination, pending-job updates, related entries, dumps, monitored tags, SQL formatting/highlighting, JSON inspection, and clipboard contents. +- Light/dark styling, responsive layout, modal/dropdown behavior, and supported HTTP development installations. +- `Telescope::css()`, `js()`, script variables, nonce handling, and the Blade shell. The dashboard assets are inlined; a build that succeeds but emits unresolved external chunks is not acceptable. + +### 2. Move onto Vue 3 and the Horizon application pattern + +Use package-manager commands to update `src/telescope/package.json` and its npm lockfile. Install supported compatible releases of Vue 3, Router 4, `@vitejs/plugin-vue`, Vue Test Utils 2, and `vue-json-pretty` 2. Replace `@vitejs/plugin-vue2`, Vue 2 compiler dependencies, and the Vue 2 clipboard wrapper. Declare directly imported dependencies; do not rely on npm hoisting to conceal missing declarations. + +Upgrade Telescope's standalone Vite/Vitest to supported versions compatible with these plugins and Node 24. PR 1 still uses plain Vite and npm; Vite+ and workspace/catalog changes belong to Part 2. Preserve the minimum-release-age policy and inspect changes in the complete dependency graph. Do not use `--force`, legacy-peer-deps, or a compatibility shim to pass installation. + +Follow `src/horizon/resources/js/app.js`: + +```js +import { createApp } from 'vue/dist/vue.esm-bundler.js'; +import { createRouter, createWebHistory } from 'vue-router'; + +const app = createApp({ + data() { + return { + // Telescope's existing root-owned state. + }; + }, +}); + +const router = createRouter({ + history: createWebHistory(routerBasePath), + routes: Routes, +}); + +app.use(router); +app.component('preview-screen', PreviewScreen); +app.mixin(Base); +app.mount('#telescope'); +``` + +This is a structural example, not replacement code: retain all state, registrations, listeners, and bootstrap settings. The compiler-enabled Vue import is deliberate because the root template lives in Blade. Do not copy Horizon's product-specific globals or proxy-path configuration into Telescope. Check initial navigation and route reuse rather than adding speculative waits or forcing remounts. + +Use `defineConfig` and the Vue 3 plugin in Telescope's build and test configs. Configure required Vue production feature flags using the plugin's documented behavior. Retain current output locations and the inline-compatible runtime format. No `@vue/compat`, dual Vue runtime, runtime version detection, or Vue 2 translation layer. + +### 3. Convert templates, ownership, and lifecycle behavior + +Keep existing screen/file names and route organization. Match Horizon's component import/registration style and readable Options API method layout. Remove redundant `type="text/ecmascript-6"` script attributes, unused imports/components/data, empty option blocks, and empty styles when no longer needed. Keep useful behavior comments and the intentional upstream exclusion notes. + +- Replace `slot`/`slot-scope` with `#name`/`v-slot`. Convert named slots on real elements into `