CLAUDE.md

@@ -1,18 +1,15 @@
 # Toes - Claude Code Guide
 
 ## What It Is
-
 Personal web server framework that auto-discovers and runs multiple web apps on your home network. "Set it up, turn it on, forget about the cloud."
 
 ## How It Works
-
 1. Host server scans `/apps` directory for valid apps
 2. Valid app = has `package.json` with `scripts.toes` entry
 3. Each app spawned as child process with unique port (3001+)
 4. Dashboard UI shows all apps with current status, logs, and links
 
 ## Key Files
-
 - `src/server/apps.ts` - **The heart**: app discovery, process management, lifecycle
 - `src/server/index.tsx` - Entry point (minimal, just initializes Hype)
 - `src/pages/index.tsx` - Dashboard UI
@@ -20,107 +17,32 @@ Personal web server framework that auto-discovers and runs multiple web apps on
 - `TODO.md` - User-maintained task list (read this!)
 
 ## Tech Stack
-
 - **Bun** runtime (not Node)
 - **Hype** (custom HTTP framework wrapping Hono) from git+https://git.nose.space/defunkt/hype
 - **Forge** (typed CSS-in-JS) from git+https://git.nose.space/defunkt/forge
 - TypeScript + Hono JSX
 
 ## Running
-
 ```bash
 bun run --hot src/server/index.tsx  # Dev mode with hot reload
 ```
 
 ## App Structure
-
 ```tsx
 // apps/example/index.tsx
-import { Hype } from "hype"
+import { Hype } from 'hype'
 const app = new Hype()
-app.get("/", (c) => c.html(<h1>Content</h1>))
+app.get('/', c => c.html(<h1>Content</h1>))
 export default app.defaults
 ```
 
 ## Conventions
-
 - Apps get `PORT` env var from host
 - Each app is isolated process with own dependencies
 - No path-based routing - apps run on separate ports
 - `DATA_DIR` env controls where apps are discovered
 
 ## Current State
-
 - Core infrastructure: ✓ Complete (discovery, spawn, watch, ports, UI)
 - Apps: basic, profile (working); risk, tictactoe (empty)
 - Check TODO.md for planned features
-
-## Coding Guidelines
-
-TS files should be organized in the following way:
-
-- imports
-- re-exports
-- const/lets
-- enums
-- interfaces
-- types
-- classes
-- functions
-- module init (top level function calls)
-
-In each section, put the `export`s first, in alphabetical order.
-
-Then, after the `export`s (if there were any), put everything else,
-also in alphabetical order.
-
-For single-line functions, use `const fn = () => {}` and put them in the
-"functions" section of the file.
-
-All other functions use the `function blah(){}` format.
-
-Example:
-
-```ts
-import { code } from "coders"
-import { something } from "somewhere"
-
-export type { SomeType }
-
-const RETRY_TIMES = 5
-const WIDTH = 480
-
-enum State {
-  Stopped,
-  Starting,
-  Running,
-}
-
-interface Config {
-  name: string
-  port: number
-}
-
-type Handler = (req: Request) => Response
-
-class App {
-  config: Config
-
-  constructor(config: Config) {
-    this.config = config
-  }
-}
-
-const isApp = (name: string) =>
-  apps.has(name)
-
-function createApp(name: string): App {
-  const app = new App({ name, port: 3000 })
-  apps.set(name, app)
-  return app
-}
-
-function start(app: App): void {
-  console.log(`Starting ${app.config.name}`)
-}
-```

TODO.txt

@@ -18,15 +18,9 @@
 
 ## cli
 
-[x] `toes --help`
+[ ] `toes --help`
-[x] `toes --version`
+[ ] `toes --version`
-[x] `toes list`
+[ ] `toes list`
-[x] `toes start <app>`
-[x] `toes stop <app>`
-[x] `toes restart <app>`
-[x] `toes open <app>`
-[x] `toes logs <app>`
-[x] `toes logs -f <app>`
 [ ] `toes new`
 [ ] `toes pull`
 [ ] `toes push`

bin/toes

@@ -1,3 +0,0 @@
-#!/usr/bin/env bun
-
-import '../src/cli/index.ts'

bun.lock

@@ -5,10 +5,8 @@
     "": {
       "name": "toes",
       "dependencies": {
-        "commander": "^14.0.2",
         "forge": "git+https://git.nose.space/defunkt/forge",
         "hype": "git+https://git.nose.space/defunkt/hype",
-        "kleur": "^4.1.5",
       },
       "devDependencies": {
         "@types/bun": "latest",
@@ -25,8 +23,6 @@
 
     "bun-types": ["bun-types@1.3.7", "", { "dependencies": { "@types/node": "*" } }, "sha512-qyschsA03Qz+gou+apt6HNl6HnI+sJJLL4wLDke4iugsE6584CMupOtTY1n+2YC9nGVrEKUlTs99jjRLKgWnjQ=="],
 
-    "commander": ["commander@14.0.2", "", {}, "sha512-TywoWNNRbhoD0BXs1P3ZEScW8W5iKrnbithIl0YH+uCmBd0QpPOA8yc82DS3BIE5Ma6FnBVUsJ7wVUDz4dvOWQ=="],
-
     "forge": ["forge@git+https://git.nose.space/defunkt/forge#debfd73ab22c50f66ccc93cb41164c234f78a920", { "peerDependencies": { "typescript": "^5" } }, "debfd73ab22c50f66ccc93cb41164c234f78a920"],
 
     "hono": ["hono@4.11.7", "", {}, "sha512-l7qMiNee7t82bH3SeyUCt9UF15EVmaBvsppY2zQtrbIhl/yzBTny+YUxsVjSjQ6gaqaeVtZmGocom8TzBlA4Yw=="],

package.json

@@ -14,9 +14,7 @@
     "typescript": "^5.9.2"
   },
   "dependencies": {
-    "commander": "^14.0.2",
-    "forge": "git+https://git.nose.space/defunkt/forge",
     "hype": "git+https://git.nose.space/defunkt/hype",
-    "kleur": "^4.1.5"
+    "forge": "git+https://git.nose.space/defunkt/forge"
   }
 }

src/cli/index.ts

@@ -1,225 +0,0 @@
-import { program } from 'commander'
-import { join } from 'path'
-import type { App, LogLine } from '@types'
-import color from 'kleur'
-import { APPS_DIR } from '$apps'
-
-const HOST = `http://localhost:${process.env.PORT ?? 3000}`
-
-const STATE_ICONS: Record<string, string> = {
-  running: color.green('●'),
-  starting: color.yellow('◎'),
-  stopped: color.gray('◯'),
-  invalid: color.red('◌'),
-}
-
-async function get<T>(url: string): Promise<T | undefined> {
-  try {
-    const res = await fetch(join(HOST, url))
-    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
-    return await res.json()
-  } catch (error) {
-    console.error(error)
-  }
-}
-
-async function post<T, B = unknown>(url: string, body?: B): Promise<T | undefined> {
-  try {
-    const res = await fetch(join(HOST, url), {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
-    })
-    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
-    return await res.json()
-  } catch (error) {
-    console.error(error)
-  }
-}
-
-async function infoApp(name: string) {
-  const app: App | undefined = await get(`/api/apps/${name}`)
-  if (!app) {
-    console.error(`App not found: ${name}`)
-    return
-  }
-
-  const icon = STATE_ICONS[app.state] ?? '◯'
-  console.log(`${icon} ${color.bold(app.name)}`)
-  console.log(`  State:   ${app.state}`)
-  if (app.port) {
-    console.log(`  Port:    ${app.port}`)
-    console.log(`  URL:     http://localhost:${app.port}`)
-  }
-  if (app.started) {
-    const uptime = Date.now() - app.started
-    const seconds = Math.floor(uptime / 1000) % 60
-    const minutes = Math.floor(uptime / 60000) % 60
-    const hours = Math.floor(uptime / 3600000)
-    const parts = []
-    if (hours) parts.push(`${hours}h`)
-    if (minutes) parts.push(`${minutes}m`)
-    parts.push(`${seconds}s`)
-    console.log(`  Uptime:  ${parts.join(' ')}`)
-  }
-  if (app.error) console.log(`  Error:   ${color.red(app.error)}`)
-}
-
-async function listApps() {
-  const apps: App[] | undefined = await get('/api/apps')
-  if (!apps) return
-
-  for (const app of apps) {
-    console.log(`${STATE_ICONS[app.state] ?? '◯'} ${app.name}`)
-  }
-}
-
-const startApp = async (app: string) => {
-  await post(`/api/apps/${app}/start`)
-}
-
-const stopApp = async (app: string) => {
-  await post(`/api/apps/${app}/stop`)
-}
-
-const restartApp = async (app: string) => {
-  await post(`/api/apps/${app}/restart`)
-}
-
-const printLog = (line: LogLine) =>
-  console.log(`${new Date(line.time).toLocaleTimeString()} ${line.text}`)
-
-async function logApp(name: string, options: { follow?: boolean }) {
-  if (options.follow) {
-    await tailLogs(name)
-    return
-  }
-
-  const logs: LogLine[] | undefined = await get(`/api/apps/${name}/logs`)
-  if (!logs) {
-    console.error(`App not found: ${name}`)
-    return
-  }
-  if (logs.length === 0) {
-    console.log('No logs yet')
-    return
-  }
-  for (const line of logs) {
-    printLog(line)
-  }
-}
-
-async function tailLogs(name: string) {
-  const url = join(HOST, `/api/apps/${name}/logs/stream`)
-  const res = await fetch(url)
-  if (!res.ok) {
-    console.error(`App not found: ${name}`)
-    return
-  }
-  if (!res.body) return
-
-  const reader = res.body.getReader()
-  const decoder = new TextDecoder()
-  let buffer = ''
-
-  while (true) {
-    const { done, value } = await reader.read()
-    if (done) break
-
-    buffer += decoder.decode(value, { stream: true })
-    const lines = buffer.split('\n\n')
-    buffer = lines.pop() ?? ''
-
-    for (const line of lines) {
-      if (line.startsWith('data: ')) {
-        const data = JSON.parse(line.slice(6)) as LogLine
-        printLog(data)
-      }
-    }
-  }
-}
-
-async function openApp(name: string) {
-  const app: App | undefined = await get(`/api/apps/${name}`)
-  if (!app) {
-    console.error(`App not found: ${name}`)
-    return
-  }
-  if (app.state !== 'running') {
-    console.error(`App is not running: ${name}`)
-    return
-  }
-  const url = `http://localhost:${app.port}`
-  console.log(`Opening ${url}`)
-  Bun.spawn(['open', url])
-}
-
-program
-  .name('toes')
-  .version('0.0.1', '-v, --version')
-
-program
-  .command('info')
-  .description('Show info for an app')
-  .argument('<name>', 'app name')
-  .action(infoApp)
-
-program
-  .command('list')
-  .description('List all apps')
-  .action(listApps)
-
-program
-  .command('start')
-  .description('Start an app')
-  .argument('<name>', 'app name')
-  .action(startApp)
-
-program
-  .command('stop')
-  .description('Stop an app')
-  .argument('<name>', 'app name')
-  .action(stopApp)
-
-program
-  .command('restart')
-  .description('Restart an app')
-  .argument('<name>', 'app name')
-  .action(restartApp)
-
-program
-  .command('logs')
-  .description('Show logs for an app')
-  .argument('<name>', 'app name')
-  .option('-f, --follow', 'follow log output')
-  .action(logApp)
-
-program
-  .command('log', { hidden: true })
-  .argument('<name>', 'app name')
-  .option('-f, --follow', 'follow log output')
-  .action(logApp)
-
-program
-  .command('open')
-  .description('Open an app in browser')
-  .argument('<name>', 'app name')
-  .action(openApp)
-
-program
-  .command('new')
-  .description('Create a new app')
-  .argument('<name>', 'app name')
-  .action(name => {
-    // ...
-  })
-
-program
-  .command('push')
-  .description('Push app to server')
-  .option('-f, --force', 'force overwrite')
-  .action(options => {
-    // ...
-  })
-
-program.parse()

src/server/apps.ts

@@ -1,99 +1,52 @@
-import type { App as SharedApp, AppState, LogLine } from '@types'
 import type { Subprocess } from 'bun'
-import { existsSync, readdirSync, readFileSync, statSync, watch, writeFileSync } from 'fs'
+import {
+  existsSync, readdirSync, readFileSync, writeFileSync,
+  statSync, watch
+} from 'fs'
 import { join } from 'path'
+import type { App as SharedApp, AppState, LogLine } from '../shared/types'
 
-export type { AppState } from '@types'
+export type { AppState } from '../shared/types'
-
-export const APPS_DIR = join(process.env.DATA_DIR ?? '.', 'apps')
 
 const DEFAULT_EMOJI = '🖥️'
+const APPS_DIR = join(process.env.DATA_DIR ?? '.', 'apps')
 const MAX_LOGS = 100
-const _apps = new Map<string, App>()
-const _listeners = new Set<() => void>()
-
-let NEXT_PORT = 3001
 
 export type App = SharedApp & {
   proc?: Subprocess
 }
 
-type LoadResult = { pkg: any; error?: string }
+const _apps = new Map<string, App>()
 
-export const allApps = (): App[] =>
+// Change notification system
-  Array.from(_apps.values())
+const _listeners = new Set<() => void>()
-    .sort((a, b) => a.name.localeCompare(b.name))
+export const onChange = (cb: () => void) => {
-
-export const getApp = (dir: string): App | undefined =>
-  _apps.get(dir)
-
-export const runApps = () =>
-  allAppDirs().filter(isApp).forEach(startApp)
-
-export const runningApps = (): App[] =>
-  allApps().filter(a => a.state === 'running')
-
-export function initApps() {
-  discoverApps()
-  runApps()
-  watchAppsDir()
-}
-
-export function onChange(cb: () => void) {
   _listeners.add(cb)
   return () => _listeners.delete(cb)
 }
-
+const update = () => _listeners.forEach(cb => cb())
-export function startApp(dir: string) {
-  const app = _apps.get(dir)
-  if (!app || app.state !== 'stopped') return
-  if (!isApp(dir)) return
-  runApp(dir, getPort())
-}
-
-export function stopApp(dir: string) {
-  const app = _apps.get(dir)
-  if (!app || app.state !== 'running') return
-
-  info(dir, 'Stopping...')
-  app.state = 'stopping'
-  update()
-  app.proc?.kill()
-}
-
-export function updateAppIcon(dir: string, icon: string) {
-  const { pkg, error } = loadApp(dir)
-  if (error) throw new Error(error)
-
-  pkg.toes ??= {}
-  pkg.toes.icon = icon
-  saveApp(dir, pkg)
-}
 
 const err = (app: string, ...msg: string[]) =>
   console.error('🐾', `${app}:`, ...msg)
 
-const getPort = () => NEXT_PORT++
-
 const info = (app: string, ...msg: string[]) =>
   console.log('🐾', `${app}:`, ...msg)
 
-const isApp = (dir: string): boolean =>
-  !loadApp(dir).error
-
 const log = (app: string, ...msg: string[]) =>
   console.log(`<${app}>`, ...msg)
 
-const update = () => _listeners.forEach(cb => cb())
+/** Returns all directory names in APPS_DIR */
-
+const allAppDirs = () => {
-function allAppDirs() {
   return readdirSync(APPS_DIR, { withFileTypes: true })
     .filter(e => e.isDirectory())
     .map(e => e.name)
     .sort()
 }
 
-function discoverApps() {
+let NEXT_PORT = 3001
+const getPort = () => NEXT_PORT++
+
+const discoverApps = () => {
   for (const dir of allAppDirs()) {
     const { pkg, error } = loadApp(dir)
     const state: AppState = error ? 'invalid' : 'stopped'
@@ -102,15 +55,12 @@ function discoverApps() {
   }
 }
 
-function isDir(path: string): boolean {
+export const runApps = () =>
-  try {
+  allAppDirs().filter(isApp).forEach(startApp)
-    return statSync(path).isDirectory()
-  } catch {
-    return false
-  }
-}
 
-function loadApp(dir: string): LoadResult {
+type LoadResult = { pkg: any; error?: string }
+
+const loadApp = (dir: string): LoadResult => {
   try {
     const file = readFileSync(join(APPS_DIR, dir, 'package.json'), 'utf-8')
 
@@ -136,7 +86,24 @@ function loadApp(dir: string): LoadResult {
   }
 }
 
-async function runApp(dir: string, port: number) {
+const saveApp = (dir: string, pkg: any) => {
+  const path = join(APPS_DIR, dir, 'package.json')
+  writeFileSync(path, JSON.stringify(pkg, null, 2) + '\n')
+}
+
+export const updateAppIcon = (dir: string, icon: string) => {
+  const { pkg, error } = loadApp(dir)
+  if (error) throw new Error(error)
+
+  pkg.toes ??= {}
+  pkg.toes.icon = icon
+  saveApp(dir, pkg)
+}
+
+const isApp = (dir: string): boolean =>
+  !loadApp(dir).error
+
+const runApp = async (dir: string, port: number) => {
   const { pkg, error } = loadApp(dir)
   if (error) return
 
@@ -208,12 +175,35 @@ async function runApp(dir: string, port: number) {
   })
 }
 
-function saveApp(dir: string, pkg: any) {
+/** Returns all apps */
-  const path = join(APPS_DIR, dir, 'package.json')
+export const allApps = (): App[] =>
-  writeFileSync(path, JSON.stringify(pkg, null, 2) + '\n')
+  Array.from(_apps.values())
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+/** Returns only running apps (for backwards compatibility) */
+export const runningApps = (): App[] =>
+  allApps().filter(a => a.state === 'running')
+
+export const getApp = (dir: string): App | undefined => _apps.get(dir)
+
+export const startApp = (dir: string) => {
+  const app = _apps.get(dir)
+  if (!app || app.state !== 'stopped') return
+  if (!isApp(dir)) return
+  runApp(dir, getPort())
 }
 
-function watchAppsDir() {
+export const stopApp = (dir: string) => {
+  const app = _apps.get(dir)
+  if (!app || app.state !== 'running') return
+
+  info(dir, 'Stopping...')
+  app.state = 'stopping'
+  update()
+  app.proc?.kill()
+}
+
+const watchAppsDir = () => {
   watch(APPS_DIR, { recursive: true }, (event, filename) => {
     if (!filename) return
 
@@ -275,3 +265,17 @@ function watchAppsDir() {
     }
   })
 }
+
+function isDir(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+export const initApps = () => {
+  discoverApps()
+  runApps()
+  watchAppsDir()
+}

src/server/index.tsx

@@ -1,18 +1,12 @@
-import { allApps, initApps, onChange, startApp, stopApp, updateAppIcon } from '$apps'
-import type { App as SharedApp } from '@types'
-import type { App as BackendApp } from '$apps'
 import { Hype } from 'hype'
-
+import { allApps, initApps, onChange, startApp, stopApp, updateAppIcon } from './apps'
-// BackendApp -> SharedApp
+import type { App as SharedApp } from '../shared/types'
-function convert(app: BackendApp): SharedApp {
-  const clone = { ...app }
-  delete clone.proc
-  delete clone.logs
-  return clone
-}
 
 const app = new Hype({ layout: false })
 
+console.log('🐾 Toes!')
+initApps()
+
 // SSE endpoint for real-time app state updates
 app.get('/api/apps/stream', c => {
   const encoder = new TextEncoder()
@@ -56,53 +50,14 @@ app.get('/api/apps/stream', c => {
   })
 })
 
-app.get('/api/apps', c =>
+app.get('/api/apps', c => {
-  c.json(allApps().map(convert))
+  const apps = allApps().map(app => {
-)
+    const clone = { ...app }
-
+    delete clone.proc
-app.get('/api/apps/:app', c => {
+    delete clone.logs
-  const appName = c.req.param('app')
+    return clone
-  if (!appName) return c.json({ error: 'App not found' }, 404)
-
-  const app = allApps().find(a => a.name === appName)
-  if (!app) return c.json({ error: 'App not found' }, 404)
-
-  return c.json(convert(app))
   })
-
+  return c.json(apps)
-app.get('/api/apps/:app/logs', c => {
-  const appName = c.req.param('app')
-  if (!appName) return c.json({ error: 'App not found' }, 404)
-
-  const app = allApps().find(a => a.name === appName)
-  if (!app) return c.json({ error: 'App not found' }, 404)
-
-  return c.json(app.logs ?? [])
-})
-
-app.sse('/api/apps/:app/logs/stream', (send, c) => {
-  const appName = c.req.param('app')
-  const targetApp = allApps().find(a => a.name === appName)
-  if (!targetApp) return
-
-  let lastLogCount = 0
-
-  const sendNewLogs = () => {
-    const currentApp = allApps().find(a => a.name === appName)
-    if (!currentApp) return
-
-    const logs = currentApp.logs ?? []
-    const newLogs = logs.slice(lastLogCount)
-    lastLogCount = logs.length
-
-    for (const line of newLogs) {
-      send(line)
-    }
-  }
-
-  sendNewLogs()
-  const unsub = onChange(sendNewLogs)
-  return () => unsub()
 })
 
 app.post('/api/apps/:app/start', c => {
@@ -143,7 +98,4 @@ app.post('/api/apps/:app/icon', c => {
   }
 })
 
-console.log('🐾 Toes!')
-initApps()
-
 export default app.defaults

tsconfig.json

@@ -1,39 +1,30 @@
 {
   "compilerOptions": {
     // Environment setup & latest features
-    "lib": [
+    "lib": ["ESNext", "DOM"],
-      "ESNext",
-      "DOM"
-    ],
     "target": "ESNext",
     "module": "Preserve",
     "moduleDetection": "force",
     "jsx": "react-jsx",
     "jsxImportSource": "hono/jsx",
     "allowJs": true,
+
     // Bundler mode
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
     "noEmit": true,
+
     // Best practices
     "strict": true,
     "skipLibCheck": true,
     "noFallthroughCasesInSwitch": true,
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,
+
     // Some stricter flags (disabled by default)
     "noUnusedLocals": false,
     "noUnusedParameters": false,
-    "noPropertyAccessFromIndexSignature": false,
+    "noPropertyAccessFromIndexSignature": false
-    "baseUrl": ".",
-    "paths": {
-      "$*": [
-        "./src/server/*"
-      ],
-      "@*": [
-        "./src/shared/*"
-      ]
-    }
   }
 }