@telemetryos/cli 1.8.3 → 1.10.0

package/dist/utils/path-utils.js

@@ -0,0 +1,99 @@
+/**
+ * Utility functions for path handling and project name derivation
+ */
+import path from 'node:path';
+/**
+ * Converts a string to kebab-case
+ *
+ * @param str - The string to convert
+ * @returns The kebab-cased string
+ *
+ * @example
+ * toKebabCase('MyApp') // 'my-app'
+ * toKebabCase('my_app') // 'my-app'
+ * toKebabCase('My App!') // 'my-app'
+ * toKebabCase('my--app') // 'my-app'
+ */
+export function toKebabCase(str) {
+    return (str
+        .trim()
+        // Remove special characters except spaces, underscores, and hyphens
+        .replace(/[^a-zA-Z0-9\s_-]/g, '')
+        // Replace spaces and underscores with hyphens
+        .replace(/[\s_]+/g, '-')
+        // Insert hyphen before uppercase letters preceded by lowercase
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        // Convert to lowercase
+        .toLowerCase()
+        // Replace multiple consecutive hyphens with single hyphen
+        .replace(/-+/g, '-')
+        // Remove leading/trailing hyphens
+        .replace(/^-+|-+$/g, ''));
+}
+/**
+ * Derives a project name from a given path
+ *
+ * @param projectPath - The path to derive the name from
+ * @param currentWorkingDirectory - The current working directory (defaults to process.cwd())
+ * @returns The derived project name in kebab-case
+ *
+ * @example
+ * deriveProjectName('my-project') // 'my-project'
+ * deriveProjectName('apps/MyApp') // 'my-app'
+ * deriveProjectName('./', '/Users/test/MyProject') // 'my-project'
+ * deriveProjectName('../parent') // 'parent'
+ * deriveProjectName('/absolute/path/to/app') // 'app'
+ */
+export function deriveProjectName(projectPath, currentWorkingDirectory = process.cwd()) {
+    // Resolve the path to handle relative paths
+    const resolvedPath = path.resolve(currentWorkingDirectory, projectPath);
+    // Get the last segment of the path
+    const basename = path.basename(resolvedPath);
+    // Convert to kebab-case
+    return toKebabCase(basename);
+}
+/**
+ * Resolves a project path and derives the name
+ *
+ * @param projectPath - The path to resolve
+ * @param currentWorkingDirectory - The current working directory (defaults to process.cwd())
+ * @returns An object containing the resolved path and derived name
+ *
+ * @example
+ * resolveProjectPathAndName('apps/MyApp')
+ * // { resolvedPath: '/Users/user/cwd/apps/MyApp', derivedName: 'my-app' }
+ */
+export function resolveProjectPathAndName(projectPath, currentWorkingDirectory = process.cwd()) {
+    const resolvedPath = path.resolve(currentWorkingDirectory, projectPath);
+    const derivedName = deriveProjectName(projectPath, currentWorkingDirectory);
+    return { resolvedPath, derivedName };
+}
+/**
+ * Validates a project name according to npm package name requirements
+ *
+ * @param name - The project name to validate
+ * @returns true if valid, or an error message string if invalid
+ *
+ * @example
+ * validateProjectName('my-app') // true
+ * validateProjectName('') // 'Project name cannot be empty'
+ * validateProjectName('MyApp') // 'Project name must contain only lowercase letters, numbers, and hyphens'
+ */
+export function validateProjectName(name) {
+    if (!name || name.length === 0) {
+        return 'Project name cannot be empty';
+    }
+    if (name.length > 214) {
+        return 'Project name must be 214 characters or less';
+    }
+    if (name.startsWith('.') || name.startsWith('_')) {
+        return 'Project name cannot start with . or _';
+    }
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        return 'Project name must contain only lowercase letters, numbers, and hyphens';
+    }
+    if (name.startsWith('-') || name.endsWith('-')) {
+        return 'Project name cannot start or end with a hyphen';
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetryos/cli",
-  "version": "1.8.3",
+  "version": "1.10.0",
   "description": "The official TelemetryOS application CLI package. Use it to build applications that run on the TelemetryOS platform",
   "type": "module",
   "bin": {
@@ -25,11 +25,13 @@
   "license": "",
   "repository": "github:TelemetryTV/Application-API",
   "dependencies": {
-    "@telemetryos/development-application-host-ui": "^1.8.3",
+    "@telemetryos/development-application-host-ui": "^1.10.0",
     "@types/serve-handler": "^6.1.4",
     "commander": "^14.0.0",
+    "ignore": "^6.0.2",
     "inquirer": "^12.9.6",
     "serve-handler": "^6.1.6",
+    "tar": "^7.4.3",
     "zod": "^4.1.12"
   },
   "devDependencies": {

package/templates/vite-react-typescript/CLAUDE.md

@@ -13,8 +13,9 @@ tos serve          # Start dev server (or: npm run dev)
 **IMPORTANT:** Always run `npm run build` after making changes to check for TypeScript errors. Do not rely solely on the dev server.
 
 **Development Host:** http://localhost:2026
-- Settings: http://localhost:2026/settings
-- Render: http://localhost:2026/render
+Both the render and settings mounts points are visible in the development host.
+The Render mount point is presented in a resizable pane.
+The Settings mount point shows in the settings tab of the right sidebar.
 
 ## Architecture
 
@@ -101,13 +102,13 @@ const response = await proxy().fetch('https://api.example.com/data')
 
 | Task | Required Skill | Why |
 |------|----------------|-----|
+| Starting new project | `tos-requirements` | Gather requirements before coding MUST USE |
 | Building Render views | `tos-render-design` | Digital signage constraints, UI scaling, no hover/scroll |
 | Adding ANY Settings UI | `tos-settings-ui` | SDK components are required - raw HTML won't work |
-| Calling external APIs | `tos-proxy-fetch` | Proxy patterns prevent CORS errors |
 | Adding store keys | `tos-store-sync` | Hook patterns ensure Settings↔Render sync |
-| Weather integration | `tos-weather-api` | API-specific patterns and credentials |
+| Calling external APIs | `tos-proxy-fetch` | Proxy patterns prevent CORS errors |
 | Media library access | `tos-media-api` | SDK media methods and types |
-| Starting new project | `tos-requirements` | Gather requirements before coding |
+| Weather integration | `tos-weather-api` | API-specific patterns and credentials |
 | Debugging issues | `tos-debugging` | Common errors and fixes |
 
 **Never write Render layouts, Settings components, or proxy.fetch code without invoking the skill first.**

package/templates/vite-react-typescript/_claude/settings.local.json

@@ -11,7 +11,8 @@
       "Skill(tos-store-sync)",
       "Skill(tos-weather-api)",
       "Bash(npm run build:*)",
-      "Bash(npm run dev:*)"
+      "Bash(npm run dev:*)",
+      "WebFetch(domain:docs.telemetryos.com)"
     ]
   }
 }

package/templates/vite-react-typescript/_claude/skills/tos-render-design/SKILL.md

@@ -1,33 +1,63 @@
 ---
 name: tos-render-design
-description: Design patterns for TelemetryOS Render views. Use when building or reviewing Render view layouts, handling responsive scaling, or ensuring digital signage best practices.
+description: Design patterns for TelemetryOS Render views. Use when building display-only digital signage OR interactive kiosks. Covers responsive scaling, UI patterns, and interaction handling for both models.
 ---
 
 # Render View Design
 
-TelemetryOS Render views display on digital signage—TVs, video walls, and displays viewed from a distance with no user interaction. This fundamentally shapes how to design them.
+TelemetryOS Render views support both **digital signage** (display-only) and **interactive kiosks** (touch-enabled). Understanding which pattern you're building determines how you handle user interaction and state management.
 
 > **Note:** The init project already provides base styles in `index.css` (viewport scaling, box-sizing) and `Render.css` (`.render` class with padding, overflow, flexbox). Build on these—don't override them.
 
-## Digital Signage Constraints
+---
+
+## Interaction Models
+
+TelemetryOS render views support two interaction models. Both use `@telemetryos/sdk` with the same architecture—the difference is whether the render view includes onClick handlers.
+
+### Digital Signage (Display-Only)
+
+**Use for:** Information displays, dashboards, menu boards, announcements
+
+- Content updates automatically via store subscriptions
+- No user interaction (no mouse, keyboard, touch input)
+- No onClick handlers in render view
+- Viewed from a distance
+- Updates driven by timers, external data, or Settings changes
+
+### Interactive Kiosk (Touch-Enabled)
+
+**Use for:** Wayfinding, directories, check-in systems, search interfaces
+
+- Users can touch/click elements on screen
+- onClick handlers for buttons, navigation, forms
+- Idle timeout returns to home screen after inactivity
+- Touch feedback with :active states (not :hover)
+- Manages interaction state (current screen, navigation history)
+
+---
+
+## Digital Signage Pattern (Display-Only)
+
+For apps where users only **view** content from a distance.
 
 ### No User Interaction
 
-Unless building for kiosk/touchscreen scenarios, assume **no mouse, keyboard, or touch input**:
+Assume **no mouse, keyboard, or touch input**:
 
 ```css
-/* WRONG - No one will hover */
+/* WRONG - No one will hover on digital signage */
 .button:hover {
   background: blue;
 }
 
-/* WRONG - No one will focus */
+/* WRONG - No one will focus elements */
 .input:focus {
   outline: 2px solid blue;
 }
 ```
 
-Avoid `:hover`, `:focus`, `:active`, and similar interaction pseudo-classes.
+Avoid `:hover`, `:focus`, `:active`, and similar interaction pseudo-classes for display-only apps.
 
 ### No Scrolling
 
@@ -55,8 +85,150 @@ Content **must fit the viewport**. There's no user to scroll:
 
 If content might overflow, truncate it or conditionally hide elements—never show a scrollbar.
 
+---
+
+## Interactive Kiosk Pattern (Touch-Enabled)
+
+For apps where users **interact** with the screen via touch or click.
+
+### onClick Handlers
+
+Add click handlers to interactive elements:
+
+```typescript
+function Render() {
+  const [screen, setScreen] = useState('home')
+
+  return (
+    <div className="render">
+      {screen === 'home' && (
+        <button
+          className="kiosk-button"
+          onClick={() => setScreen('search')}
+        >
+          Search Directory
+        </button>
+      )}
+      {screen === 'search' && (
+        <SearchScreen onBack={() => setScreen('home')} />
+      )}
+    </div>
+  )
+}
+```
+
+### Touch Feedback (:active states)
+
+Use `:active` pseudo-class for touch feedback (NOT `:hover`):
+
+```css
+.kiosk-button {
+  padding: 2rem 4rem;
+  font-size: 3rem;
+  background: blue;
+  color: white;
+  border: none;
+  border-radius: 1rem;
+  transition: transform 0.1s, background 0.1s;
+}
+
+/* Touch feedback - user sees visual response when tapping */
+.kiosk-button:active {
+  transform: scale(0.95);
+  background: darkblue;
+}
+```
+
+**Why :active instead of :hover?**
+- Touch devices don't have hover
+- :active triggers on touch/click
+- Provides immediate visual feedback
+
+### Idle Timeout Pattern
+
+Return to home screen after inactivity:
+
+```typescript
+function Render() {
+  const [screen, setScreen] = useState('home')
+  const [lastInteraction, setLastInteraction] = useState(Date.now())
+
+  // Return to home after 30 seconds of inactivity
+  useEffect(() => {
+    const timeout = setTimeout(() => {
+      const elapsed = Date.now() - lastInteraction
+      if (elapsed > 30000 && screen !== 'home') {
+        setScreen('home')
+      }
+    }, 30000)
+
+    return () => clearTimeout(timeout)
+  }, [lastInteraction, screen])
+
+  const handleInteraction = (newScreen: string) => {
+    setScreen(newScreen)
+    setLastInteraction(Date.now())
+  }
+
+  return (
+    <div className="render">
+      {screen === 'home' && (
+        <button onClick={() => handleInteraction('search')}>
+          Search
+        </button>
+      )}
+    </div>
+  )
+}
+```
+
+### Touch Target Sizing
+
+Make touch targets large enough to tap accurately:
+
+```css
+/* Minimum sizes for touch targets */
+.kiosk-button {
+  min-width: 15rem;  /* Large enough to tap */
+  min-height: 8rem;
+  padding: 2rem 4rem;
+  font-size: 3rem;   /* Large, readable text */
+}
+```
+
+**Guidelines:**
+- Minimum 8rem height for buttons
+- 2rem padding minimum
+- 3rem font size minimum for buttons
+- Gap of at least 1rem between interactive elements
+
+### Store State for Navigation
+
+Use device store to persist state across composition changes:
+
+```typescript
+// hooks/store.ts
+import { createUseDeviceStoreState } from '@telemetryos/sdk/react'
+
+export const useKioskScreenState = createUseDeviceStoreState<string>(
+  'kiosk-screen',
+  'home'
+)
+
+// Render.tsx
+const [_isLoading, screen, setScreen] = useKioskScreenState()
+```
+
+**Why device store?**
+- Persists state on the device (survives composition changes)
+- Doesn't sync to other devices (screen state is device-local)
+
+---
+
 ## UI Scale Hooks
 
+**Applies to both digital signage and interactive kiosks.**
+
 Displays range from tablets to 8K video walls. Standard CSS pixels create inconsistent sizing. The SDK provides hooks that redefine `rem` as viewport-relative:
 
 ### useUiScaleToSetRem(uiScale)
@@ -101,8 +273,12 @@ export function Render() {
 }
 ```
 
+---
+
 ## Best Practices
 
+**Applies to both digital signage and interactive kiosks.**
+
 ### Use rem for Everything
 
 All sizing should use `rem` to scale with the UI scale setting:
@@ -200,10 +376,14 @@ function Dashboard() {
 }
 ```
 
-## Complete Example
+---
+
+## Complete Examples
+
+### Digital Signage Example (Display-Only)
 
 ```typescript
-// Render.tsx - Building on the init project's .render class
+// Render.tsx - Display-only dashboard
 import { useUiScaleToSetRem, useUiAspectRatio } from '@telemetryos/sdk/react'
 import { useUiScaleStoreState } from '../hooks/store'
 import './Render.css'
@@ -241,7 +421,7 @@ export function Render() {
 ```
 
 ```css
-/* Render.css - Add to existing styles, don't override .render base */
+/* Render.css - Display-only styles */
 .render__header {
   flex-shrink: 0;
   margin-bottom: 2rem;
@@ -278,6 +458,112 @@ export function Render() {
 }
 ```
 
+### Interactive Kiosk Example (Touch-Enabled)
+
+```typescript
+// Render.tsx - Interactive kiosk with navigation
+import { useState, useEffect } from 'react'
+import { useUiScaleToSetRem } from '@telemetryos/sdk/react'
+import { useUiScaleStoreState } from '../hooks/store'
+import './Render.css'
+
+export function Render() {
+  const [isLoading, uiScale] = useUiScaleStoreState()
+  const [screen, setScreen] = useState('home')
+  const [lastInteraction, setLastInteraction] = useState(Date.now())
+
+  useUiScaleToSetRem(uiScale)
+
+  // Idle timeout - return to home after 30 seconds
+  useEffect(() => {
+    const timeout = setTimeout(() => {
+      const elapsed = Date.now() - lastInteraction
+      if (elapsed > 30000 && screen !== 'home') {
+        setScreen('home')
+      }
+    }, 30000)
+
+    return () => clearTimeout(timeout)
+  }, [lastInteraction, screen])
+
+  const handleInteraction = (newScreen: string) => {
+    setScreen(newScreen)
+    setLastInteraction(Date.now())
+  }
+
+  if (isLoading) return null
+
+  return (
+    <div className="render">
+      {screen === 'home' && (
+        <div className="kiosk-home">
+          <h1 className="kiosk-home__title">Welcome</h1>
+          <button
+            className="kiosk-button"
+            onClick={() => handleInteraction('search')}
+          >
+            Search Directory
+          </button>
+          <button
+            className="kiosk-button"
+            onClick={() => handleInteraction('map')}
+          >
+            View Map
+          </button>
+        </div>
+      )}
+
+      {screen === 'search' && (
+        <SearchScreen onBack={() => handleInteraction('home')} />
+      )}
+
+      {screen === 'map' && (
+        <MapScreen onBack={() => handleInteraction('home')} />
+      )}
+    </div>
+  )
+}
+```
+
+```css
+/* Render.css - Interactive kiosk styles */
+.kiosk-home {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 3rem;
+  height: 100%;
+}
+
+.kiosk-home__title {
+  font-size: 6rem;
+  margin: 0;
+}
+
+/* Touch-friendly button with :active feedback */
+.kiosk-button {
+  min-width: 20rem;
+  min-height: 8rem;
+  padding: 2rem 4rem;
+  font-size: 3rem;
+  background: #0066cc;
+  color: white;
+  border: none;
+  border-radius: 1rem;
+  cursor: pointer;
+  transition: transform 0.1s, background 0.1s;
+}
+
+/* Touch feedback - scales down when tapped */
+.kiosk-button:active {
+  transform: scale(0.95);
+  background: #0052a3;
+}
+```
+
+---
+
 ## Store Hook for UI Scale
 
 Create a store hook to let admins adjust the UI scale:
@@ -318,15 +604,21 @@ export function Settings() {
 }
 ```
 
+---
+
 ## Common Mistakes
 
 | Mistake | Problem | Fix |
 |---------|---------|-----|
 | Using `px` units | Won't scale across resolutions | Use `rem` everywhere |
-| Adding `:hover` styles | No mouse on digital signage | Remove interaction states |
+| Adding `:hover` styles on digital signage | No mouse on display-only apps | Remove interaction states for display-only |
+| Using `:hover` on interactive kiosks | No hover on touch devices | Use `:active` instead for touch feedback |
 | Using `overflow: scroll` | No user to scroll | Use `overflow: hidden`, truncate content |
 | Fixed heights in `px` | Breaks on different aspect ratios | Use `vh`, `%`, or flex |
-| Forgetting `useUiScaleToSetRem()` | `rem` units won't scale properly | Call it once in Render view with the uiScale from `useUiScaleStoreState()` |
+| Forgetting `useUiScaleToSetRem()` | `rem` units won't scale properly | Call it once in Render view with uiScale |
 | Text below 2rem | Unreadable from viewing distance | Minimum 2rem for body text |
+| Small touch targets on kiosks | Hard to tap accurately | Minimum 8rem height, 2rem padding, 3rem font |
+| No idle timeout on kiosks | Kiosk stays on user's screen | Add useEffect timeout logic |
+| No touch feedback on kiosks | User unsure if tap registered | Add :active state animations |
 | Removing `.render` padding | Content cut off by bezels | Keep the ~3rem padding from init project |
 | Overriding `index.css` base styles | Breaks viewport scaling | Add new styles, don't modify base setup |