@cluesurf/tool

A Hackable Workshop 𐌎

Overview

Monorepo for the four desktop apps:

icon	glyph	app	domain	folder	package	status
	▣	term	terminal	tool/term/	@cluesurf/term	active
	▥	base	databases	tool/base/	@cluesurf/base	stub
	▦	mesh	infrastructure	tool/mesh/	@cluesurf/mesh	stub
	▤	view	logs	tool/view/	@cluesurf/view	stub

All four share a common platform (Electron + React + xterm.js + Tailwind). Per-app source lives at tool/<name>/code/; per-app Electron shell at tool/<name>/dock/. Shared platform packages will eventually live at the repo-root code/ folder (Phase 2).

(Just playing around with these right now, seeing how hackable and useful coulud make them 😁).

Develop Term

pnpm install                                # one-time
pnpm --filter @cluesurf/term-dock dev       # launch dev
pnpm --filter @cluesurf/term make           # build the runtime library
pnpm --filter @cluesurf/term-dock package:mac   # build Term.app
pnpm --filter @cluesurf/term-dock open      # launch the built .app
pnpm --filter @cluesurf/term ship           # release to GitHub + brew tap

Or via the root-level convenience scripts:

pnpm term:dev
pnpm term:make
pnpm term:package
pnpm term:open
pnpm term:ship
pnpm term:icons

Layout

tool/                                   # @cluesurf/tool monorepo root (this folder)
├── package.json
├── pnpm-workspace.yaml                 # workspaces: tool/term, tool/term/dock
├── readme.md
└── tool/
    ├── term/                           # @cluesurf/term (the runtime library)
    │   ├── code/                       # library source
    │   │   ├── base/                   # tree / types / ids / layout / theme
    │   │   ├── boot/                   # Electron main + preload entries
    │   │   ├── desktop/                # macOS / win / linux helpers
    │   │   ├── face/                   # React components (palette, find, slab, dock, …)
    │   │   ├── node/                   # PTY manager, state-store, paths, program
    │   │   ├── theme/                  # color themes (term/, dracula, monokai, …)
    │   │   └── tailwind/               # preset.css
    │   ├── dock/                       # @cluesurf/term-dock (Electron app shell)
    │   │   ├── boot/                   # Electron main + preload entry points
    │   │   ├── call/                   # `term` CLI source + bash launcher
    │   │   ├── code/                   # base.tsx, main.tsx, index.html, assets/
    │   │   └── electron.vite.config.ts
    │   ├── view/                       # term.svg, term.png (icon sources)
    │   ├── task/                       # icons.sh, ship.sh, verify.sh, trust-keychain.sh
    │   ├── test/                       # smoke tests + zone/ demo workspace
    │   ├── note/                       # user-facing docs (concepts, hotkeys, …)
    │   └── package.json
    ├── base/                           # @cluesurf/base — stub
    ├── mesh/                           # @cluesurf/mesh — stub
    └── view/                           # @cluesurf/view — stub

Naming conventions

• Each app's runtime library is @cluesurf/<name> and lives at tool/<name>/code/. Published to npm.
• Each app's Electron shell is @cluesurf/<name>-dock and lives at tool/<name>/dock/. Private — packaged via electron-builder into a separately-branded .app.
• User project config lives at <project>/.tool/<name>/ — so a project that uses both Term and View would have .tool/term/ and .tool/view/ side by side. The umbrella .tool/ dir replaces the old .rock/.

License

GPL-3.0-or-later.

ClueSurf

Made by ClueSurf, meditating on the universe ¤. Follow the work on YouTube, X, Instagram, Substack, Facebook, and LinkedIn, and browse more of our open-source work on GitHub.