{"id":48446115,"url":"https://github.com/techninja/clearstack","last_synced_at":"2026-05-25T02:04:33.598Z","repository":{"id":348598993,"uuid":"1196823983","full_name":"techninja/clearstack","owner":"techninja","description":"My best guess at a very solid, 2026 focused no-build static with optional API backed SPA and layout pattern, no need to React","archived":false,"fork":false,"pushed_at":"2026-04-03T22:37:49.000Z","size":586,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T07:47:48.640Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/techninja.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T04:33:27.000Z","updated_at":"2026-04-03T22:37:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/techninja/clearstack","commit_stats":null,"previous_names":["techninja/clearstack"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/techninja/clearstack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techninja%2Fclearstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techninja%2Fclearstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techninja%2Fclearstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techninja%2Fclearstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/techninja","download_url":"https://codeload.github.com/techninja/clearstack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techninja%2Fclearstack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31479006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T14:34:32.243Z","status":"ssl_error","status_checked_at":"2026-04-06T14:34:31.723Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-06T18:00:43.955Z","updated_at":"2026-05-25T02:04:33.592Z","avatar_url":"https://github.com/techninja.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/clearstack_logo.svg\" alt=\"Clearstack\" width=\"520\"\u003e\n\u003c/p\u003e\n\nA no-build web component framework specification — and its working proof — built entirely through LLM-human collaboration.\n\n## Why This Exists\n\nModern frontend tooling optimizes for machines: bundlers, transpilers, tree-shakers. The result is code that no human (or LLM) can read as-written in the browser. This project asks: **what if we optimized for comprehension instead?**\n\nThe core bet: if every file is small, explicit, and runs exactly as authored — with no build step between source and browser — then both humans and LLMs can reason about, generate, and maintain the codebase with dramatically less friction.\n\nThis entire repository — the specification, the file structure, every component, the server, the tests, and this README — was authored through iterative conversation between a human and an LLM. The spec was written first, then proven through implementation, then corrected where the implementation revealed gaps. The spec enforces itself: `npm run spec` checks every file against its own rules.\n\n## Quick Start\n\n```bash\nnpm install -D @techninja/clearstack\nnpx clearstack init       # scaffold a spec-compliant project\nnpm install\nnpm run dev               # http://localhost:3000\n```\n\n## What's In The Box\n\nA project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.\n\n## Specification\n\n| Document                                                                    | What It Covers                                                 |\n| --------------------------------------------------------------------------- | -------------------------------------------------------------- |\n| [FRONTEND_IMPLEMENTATION_RULES.md](./docs/FRONTEND_IMPLEMENTATION_RULES.md) | Philosophy, framework choice, project structure, atomic design |\n| [COMPONENT_PATTERNS.md](./docs/COMPONENT_PATTERNS.md)                       | Authoring, light DOM, styling, layout engine, JSDoc typing     |\n| [STATE_AND_ROUTING.md](./docs/STATE_AND_ROUTING.md)                         | Store, routing, unified app state, realtime SSE sync           |\n| [CONVENTIONS.md](./docs/CONVENTIONS.md)                                     | Naming rules, anti-patterns                                    |\n| [SERVER_AND_DEPS.md](./docs/SERVER_AND_DEPS.md)                             | Express server, import maps, vendor dependency loading         |\n| [BACKEND_API_SPEC.md](./docs/BACKEND_API_SPEC.md)                           | REST CRUD, JSON Schema via HEAD, entity management             |\n| [TESTING.md](./docs/TESTING.md)                                             | Testing philosophy, tools, patterns, phase checkpoints         |\n| [BUILD_LOG.md](./docs/BUILD_LOG.md)                                         | How this project was built — LLM-human collaboration proof     |\n| [QUICKSTART.md](./docs/QUICKSTART.md)                                       | Scaffolder setup, development workflow, updating, compliance   |\n\n## Using Clearstack\n\nInstall as a dev dependency, scaffold, and keep in sync:\n\n```bash\nnpm install -D @techninja/clearstack    # add to your project\nnpx clearstack init                     # scaffold (interactive)\nnpx clearstack init -y                  # scaffold (fullstack defaults)\nnpx clearstack init --static            # scaffold (static, no server)\nnpx clearstack update                   # sync docs (skip existing configs)\nnpx clearstack update --force           # sync docs + overwrite configs\nnpm run spec                            # check compliance\n```\n\nTwo modes: **fullstack** (Express + WebSocket + JSON DB + SSE) or **static** (localStorage, no server).\n\nSee [QUICKSTART.md](./docs/QUICKSTART.md) for the full walkthrough.\n\n## Rules That Matter\n\n- **No build tools.** ES modules served directly to the browser.\n- **≤150 lines per code file.** When it grows, it splits.\n- **Light DOM by default.** Shared styles just work.\n- **JSDoc over TypeScript.** Types without a compile step — validated by `tsc --checkJs`.\n- **Test at the boundary.** Each phase passes before the next begins.\n- **The spec checks itself.** `npm run spec code` and `npm run spec docs`.\n- **Lint and format.** ESLint + Prettier, semicolons, 2-space indent.\n\n## Scripts\n\n```bash\nnpm start           # Start server\nnpm run dev         # Start with --watch\nnpm test            # Node + browser tests\nnpm run lint        # ESLint check\nnpm run lint:fix    # ESLint auto-fix\nnpm run format      # Prettier auto-format\nnpm run typecheck   # JSDoc type validation via tsc\nnpm run spec        # Spec compliance (interactive)\nnpm run spec all    # Full spec check\nnpm run spec code   # Check code files ≤150 lines\nnpm run spec docs   # Check doc files ≤500 lines\nnpm run spec update # Sync docs from upstream\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechninja%2Fclearstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechninja%2Fclearstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechninja%2Fclearstack/lists"}