frontos 0.2.0__tar.gz

frontos-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FrontOS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frontos-0.2.0/PKG-INFO

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: frontos
+Version: 0.2.0
+Summary: Local frontend design-system server for AI coding agents.
+Author: FrontOS
+License-Expression: MIT
+Project-URL: Repository, https://github.com/imwalkinhere/frontend-system
+Project-URL: Issues, https://github.com/imwalkinhere/frontend-system/issues
+Project-URL: Changelog, https://github.com/imwalkinhere/frontend-system/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: visual
+Requires-Dist: Pillow>=10.0; extra == "visual"
+Requires-Dist: playwright>=1.44; extra == "visual"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# FrontOS
+
+FrontOS is a local frontend design-system server for AI coding agents. It registers any local project once, scans the frontend, creates project-specific design packs, generates reviewable patch artifacts, and runs strict design QA so agents stop shipping generic frontend work.
+
+The current implementation is local-first and patch-only by default. It does not upload source code, and it does not mutate registered projects unless future commands are explicitly given write permission.
+
+## Install
+
+```bash
+pipx install "git+https://github.com/imwalkinhere/frontend-system.git"
+frontos status
+```
+
+See [`docs/install.md`](docs/install.md) for virtualenv, visual extras, upgrades, Homebrew, PyPI, and release install notes.
+
+By default FrontOS stores data in `~/.frontos`. For tests or sandboxed usage:
+
+```bash
+export FRONTOS_HOME=/tmp/frontos-home
+```
+
+## Getting Started In 5 Minutes
+
+```bash
+frontos project add ~/dev/acme-crm --name acme-crm
+frontos project scan acme-crm
+frontos design-pack create acme-crm
+frontos design-pack create acme-crm --preset field-service-command
+frontos design-pack presets
+frontos repair acme-crm --route /dashboard
+```
+
+`frontos repair` returns the intended output contract:
+
+```json
+{
+  "jobId": "job_acme_crm_...",
+  "project": "acme-crm",
+  "mode": "repair_existing_frontend",
+  "route": "/dashboard",
+  "designPack": {
+    "id": "quiet-premium-ops-acme-crm-v1",
+    "styleDNA": "quiet-premium-ops",
+    "tokensGenerated": true,
+    "componentContractsGenerated": true,
+    "screenPatternsGenerated": true
+  },
+  "artifacts": {
+    "appMap": "frontos://project/acme-crm/app-map",
+    "behaviorContracts": "frontos://project/acme-crm/behavior-contracts",
+    "frontendAudit": "frontos://project/acme-crm/audit/latest",
+    "patch": "frontos://patch/patch_acme_crm_...",
+    "beforeScreenshot": null,
+    "afterScreenshot": null,
+    "qaReport": "frontos://qa/job_acme_crm_..."
+  },
+  "scores": {
+    "accessibility": 88,
+    "behaviorPreservation": 100,
+    "designQuality": 94,
+    "responsiveQuality": 91,
+    "samenessRisk": 8,
+    "stateCoverage": 94,
+    "tokenCompliance": 98
+  },
+  "status": "ready_for_review"
+}
+```
+
+The MVP focuses on local registry, code understanding, design packs, route/component repair diffs, patch artifacts, visual capture metadata, projected patch QA, HTTP, and MCP.
+
+## Optional Visual Tools
+
+Visual screenshot capture and pixel comparisons use optional dependencies:
+
+```bash
+python -m pip install -e ".[visual]"
+python -m playwright install chromium
+frontos visual doctor --check-browser
+```
+
+Without those packages, FrontOS still returns structured visual failure reports instead of crashing the workflow.
+
+## Demo
+
+Run the first repair demo against a deliberately bad CRM dashboard:
+
+```bash
+python examples/run_ugly_crm_demo.py --apply
+```
+
+The script copies `examples/ugly-crm` into an isolated workspace, registers the copy, repairs `/dashboard`, optionally applies the patch, and prints the patch id, changed files, artifact URIs, and QA scores.
+
+To include screenshot planning without launching a browser:
+
+```bash
+python examples/run_ugly_crm_demo.py --apply --visual-dry-run
+```
+
+The public demo script and before/after example assets are documented in [`docs/public-demo.md`](docs/public-demo.md).
+Demo video recording is documented in [`docs/demo-video.md`](docs/demo-video.md).
+
+## Agent Setup
+
+MCP setup snippets for Codex, Cursor, and Claude Desktop live in [`docs/agent-setup.md`](docs/agent-setup.md).
+
+You can also generate client config from the CLI:
+
+```bash
+frontos mcp config codex
+frontos mcp config cursor
+frontos mcp config claude
+python examples/mcp_smoke.py
+```
+
+The shortest instruction to give an agent is:
+
+```text
+Use FrontOS for all frontend work.
+```
+
+## Benchmark
+
+Run the local benchmark suite:
+
+```bash
+python benchmarks/run_frontos_benchmark.py
+```
+
+The benchmark generates 20 ugly frontend projects in a temporary workspace, including Next App Router, Pages Router, dynamic routes, route groups, Vite React, TanStack Query, SWR, auth-gated, and empty-state-heavy cases. It repairs each one, writes a markdown benchmark report, and checks behavior preservation, token compliance, sameness risk, generated handoff files, and patch artifacts.
+
+## CLI
+
+```bash
+frontos status
+frontos serve --host 127.0.0.1 --port 4791
+frontos stop
+
+frontos project add ~/dev/acme-crm --name acme-crm
+frontos project configure acme-crm --base-url http://127.0.0.1:3000 --dev-command "npm run dev"
+frontos project list
+frontos project scan acme-crm
+
+frontos design-pack create acme-crm
+frontos design-pack create acme-crm --preset fleet-command
+frontos design-pack presets
+frontos design-pack get acme-crm
+
+frontos patch generate acme-crm --route /dashboard
+frontos patch preview patch_acme_crm_20260530T000000 --diff
+frontos patch validate patch_acme_crm_20260530T000000
+frontos patch apply patch_acme_crm_20260530T000000 --dry-run --confirm
+frontos patch apply patch_acme_crm_20260530T000000 --confirm
+frontos patch rollback patch_acme_crm_20260530T000000 --confirm
+
+frontos visual capture acme-crm --phase before --route /dashboard
+frontos visual capture acme-crm --phase after --route /dashboard --viewport mobile
+frontos visual compare acme-crm --route /dashboard
+frontos visual latest acme-crm
+frontos visual comparison-latest acme-crm
+frontos visual doctor --check-browser
+
+frontos qa acme-crm
+frontos security audit acme-crm
+frontos repair acme-crm --route /dashboard
+frontos workflow repair acme-crm --route /dashboard --base-url http://127.0.0.1:3000 --apply --confirm
+frontos workflow repair acme-crm --route /dashboard --start-server --apply --confirm
+frontos workflow latest acme-crm
+frontos mcp
+```
+
+`frontos visual capture` uses Playwright when installed. To inspect the planned routes, viewport set, and screenshot paths without launching a browser, pass `--dry-run`.
+
+`frontos visual compare` pairs the latest `before` and `after` screenshots by route and viewport. If Pillow is installed, it writes pixel diff images and reports changed-pixel percentages. Without Pillow, it still detects byte-identical screenshots and reports when pixel diff support is missing.
+
+`frontos workflow repair` runs the coherent product loop: scan, before capture, Design Pack, patch, projected QA, optional apply, after capture, visual comparison, and final QA. Use `--skip-visual` when no local dev server is running, or `--visual-dry-run` to write planned screenshot artifacts without opening a browser.
+
+If the project has a configured runtime, `--start-server` launches the stored dev command in the registered project directory, waits for the target route URL when `--route` is provided, records the PID/log path in the workflow report, and stops the process at the end. Pass `--keep-server` only when you intentionally want that child process to stay running.
+
+Playwright, browser, and route navigation failures are returned as structured `visual_failed` workflow reports with the capture manifest attached, instead of uncaught runtime errors.
+
+Patch validation, dry-run apply, and rollback details are documented in [`docs/patch-safety.md`](docs/patch-safety.md). Visual capture troubleshooting is documented in [`docs/visual-qa.md`](docs/visual-qa.md).
+
+## HTTP API
+
+Run:
+
+```bash
+frontos serve
+```
+
+Then open `http://127.0.0.1:4791/` for the simple local project dashboard, or use the API endpoints below.
+
+Endpoints:
+
+- `GET /health`
+- `GET /`
+- `GET /projects`
+- `GET /design-presets`
+- `POST /projects`
+- `GET /projects/{id}`
+- `POST /projects/{id}/scan`
+- `GET /projects/{id}/scan/latest`
+- `POST /projects/{id}/runtime`
+- `GET /projects/{id}/runtime`
+- `POST /projects/{id}/design-pack`
+- `GET /projects/{id}/design-pack/latest`
+- `POST /projects/{id}/patch`
+- `POST /projects/{id}/visual`
+- `GET /projects/{id}/visual/latest`
+- `POST /projects/{id}/visual-compare`
+- `GET /projects/{id}/visual-comparison/latest`
+- `POST /projects/{id}/workflow-repair`
+- `GET /projects/{id}/workflow/latest`
+- `POST /projects/{id}/qa`
+- `GET /projects/{id}/qa/latest`
+- `GET /patches/{patchId}`
+- `GET /patches/{patchId}/validate`
+- `POST /patches/{patchId}/apply`
+- `POST /patches/{patchId}/validate`
+- `POST /patches/{patchId}/rollback`
+
+## MCP
+
+Run:
+
+```bash
+frontos mcp
+```
+
+The stdio server supports Content-Length framed JSON-RPC and exposes:
+
+- `frontos.register_project`
+- `frontos.scan_project`
+- `frontos.configure_project_runtime`
+- `frontos.describe_app`
+- `frontos.audit_frontend`
+- `frontos.create_design_pack`
+- `frontos.list_design_presets`
+- `frontos.get_design_pack`
+- `frontos.generate_component`
+- `frontos.generate_screen`
+- `frontos.redesign_route`
+- `frontos.generate_patch`
+- `frontos.preview_patch`
+- `frontos.validate_patch`
+- `frontos.apply_patch`
+- `frontos.compare_before_after`
+- `frontos.capture_screenshots`
+- `frontos.fix_qa_issues`
+- `frontos.repair_frontend`
+- `frontos.run_repair_workflow`
+- `frontos.run_design_qa`
+- `frontos.rollback_patch`
+
+`frontos.run_repair_workflow` accepts `startServer`, `keepServer`, and `startupTimeoutSeconds` in addition to the CLI-equivalent repair, apply, visual, and runtime options.
+
+Resources include:
+
+- `frontos://projects`
+- `frontos://project/{id}/app-map`
+- `frontos://project/{id}/ui-inventory`
+- `frontos://project/{id}/behavior-contracts`
+- `frontos://project/{id}/audit/latest`
+- `frontos://project/{id}/screenshots/latest`
+- `frontos://project/{id}/screenshots/before`
+- `frontos://project/{id}/screenshots/after`
+- `frontos://project/{id}/visual-comparison/latest`
+- `frontos://project/{id}/workflow/latest`
+- `frontos://design-pack/{id}`
+- `frontos://patch/{id}`
+- `frontos://visual-comparison/{id}`
+- `frontos://workflow/{id}`
+- `frontos://qa/{id}`
+
+Prompts include:
+
+- `frontos.repair_existing_frontend`
+- `frontos.redesign_route`
+- `frontos.design_qa_review`
+
+## What FrontOS Scans
+
+The MVP scanner understands the stack targeted in the product plan:
+
+- React, Next.js, Vite, Vue/Nuxt route scanning, and SvelteKit route scanning
+- TypeScript and JavaScript
+- Tailwind, CSS modules, and CSS
+- App/pages routes
+- Components
+- Forms, buttons, links, tables
+- `fetch` and `axios` calls
+- imported local helper data calls
+- TanStack Query, SWR, and data hooks
+- Auth, loading, empty, error, success states
+- Raw colors, arbitrary Tailwind values, and generic AI design patterns
+
+## Artifact Layout
+
+FrontOS creates the layout from the product plan:
+
+```text
+~/.frontos/
+  config.yml
+  frontos.db
+  projects/
+  design-packs/
+  scans/
+  behavior-contracts/
+  screenshots/
+  patches/
+  qa-reports/
+  registry/
+  adapters/
+```
+
+## Safety Model
+
+- Projects must be registered explicitly.
+- Default permissions are read-only and patch-only.
+- Generated patch artifacts are stored under `~/.frontos/patches`.
+- Patch apply writes only staged files listed in the patch manifest and requires `--confirm` for patch-only projects.
+- Patch validation blocks apply if target files changed after patch generation.
+- Dev-server commands reject shell control operators and run as argument vectors.
+- Route repair patches include the matched route file and local imported components when FrontOS can resolve them.
+- Patch QA scores the projected repaired files; plain `frontos qa` still audits the current source for before/after proof.
+- Screenshot capture targets the configured local base URL and stores images/reports under `~/.frontos/screenshots`.
+- Visual comparison stores before/after diff reports under `~/.frontos/screenshots/{project}/diffs`.
+- Workflow repair reports are stored under `~/.frontos/qa-reports/{project}/workflows`.
+- Rollback snapshots are captured for route and component files included in a generated patch.
+- Patch rollback restores snapshotted files and removes new files created by the patch.
+- Source code never leaves the machine in this implementation.
+- Generated patch artifacts can contain source snippets and diffs; treat `~/.frontos` as sensitive local developer data.
+- FrontOS is a local developer tool and cannot guarantee complete runtime behavior preservation. Review patches and run the app's own tests before shipping.
+- `frontos security audit <project>` scans registered source files for secret-like values and reports redacted previews.
+- Longer cloud/model upload security gates are documented in [`docs/security-review.md`](docs/security-review.md).
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m compileall -q frontos tests examples benchmarks
+python examples/run_ugly_crm_demo.py --apply
+python benchmarks/run_frontos_benchmark.py
+```
+
+GitHub Actions runs those same checks on Python 3.10, 3.11, and 3.12.
+
+Optional Playwright screenshot CI is available through the manually triggered `Visual QA` workflow.
+Publishing, PyPI trusted-publisher setup, Homebrew formula details, and Pages deployment are documented in [`docs/publishing.md`](docs/publishing.md).
+The static landing page source lives in [`site/`](site/).
+
+## License
+
+FrontOS is released under the MIT License. See [`LICENSE`](LICENSE).