biucingcli 0.9.1__py3-none-any.whl

biucingcli/template_data/frontend/template/Makefile

@@ -0,0 +1,137 @@
+APP_NAME={{PACKAGE_NAME}}
+WORKTREE_ROOT ?=$(shell git rev-parse --show-toplevel 2>/dev/null || pwd)
+WORKTREE_LABEL ?=$(shell basename "$(WORKTREE_ROOT)" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//; s/-$$//')
+WORKTREE_ID ?=$(shell printf '%s' "$(WORKTREE_ROOT)" | shasum | cut -c1-8)
+WORKTREE_SLUG ?=$(APP_NAME)-$(WORKTREE_ID)
+COMPOSE_PROJECT_NAME ?=$(WORKTREE_SLUG)
+IMAGE ?=$(WORKTREE_SLUG)
+TAG ?=dev
+IMAGE_REF := $(IMAGE):$(TAG)
+COMPOSE ?=COMPOSE_PROJECT_NAME=$(COMPOSE_PROJECT_NAME) docker compose
+DOCKER ?=docker
+BUILDER_IMAGE ?=node:20-alpine
+RUNTIME_IMAGE ?=nginx:1.27-alpine
+DEV_BASE_IMAGE ?=node:20-bookworm
+DEV_COMPOSE_FILE ?=compose.dev.yaml
+DEV_SERVICE ?=frontend-dev
+DEV_DOCKERFILE ?=Dockerfile.dev
+DEV_PORT ?=5173
+DEV_HOST_PORT ?=$(DEV_PORT)
+HOST_PORT ?=8080
+CONTAINER_PORT ?=80
+RUNTIME_CONTAINER ?=$(WORKTREE_SLUG)-production-smoke
+PNPM_HOME ?=$(WORKTREE_ROOT)/.pnpm-home/$(WORKTREE_ID)
+PNPM_STORE_DIR ?=$(WORKTREE_ROOT)/.pnpm-store
+export COMPOSE_PROJECT_NAME
+export DEV_HOST_PORT
+export DEV_PORT
+export HOST_PORT
+export CONTAINER_PORT
+export PNPM_HOME
+export PNPM_STORE_DIR
+export DEV_BASE_IMAGE
+
+.PHONY: worktree-info worktree-doctor worktree-compose-config clean-worktree bootstrap bootstrap-full install lockfile-update doctor dev dev-shell lint typecheck test verify build preview browser-install browser-smoke browser-smoke-production format format-check docker-build docker-run clean help
+
+worktree-info:
+	@printf '%s\n' "Worktree root: $(WORKTREE_ROOT)"
+	@printf '%s\n' "Worktree label: $(WORKTREE_LABEL)"
+	@printf '%s\n' "Worktree ID: $(WORKTREE_ID)"
+	@printf '%s\n' "Worktree slug: $(WORKTREE_SLUG)"
+	@printf '%s\n' "Compose project: $(COMPOSE_PROJECT_NAME)"
+	@printf '%s\n' "Dev URL: http://127.0.0.1:$(DEV_HOST_PORT)"
+	@printf '%s\n' "Runtime URL: http://127.0.0.1:$(HOST_PORT)"
+	@printf '%s\n' "Production smoke container: $(RUNTIME_CONTAINER)"
+	@printf '%s\n' "Image ref: $(IMAGE_REF)"
+	@printf '%s\n' "Builder image: $(BUILDER_IMAGE)"
+	@printf '%s\n' "Runtime base image: $(RUNTIME_IMAGE)"
+	@printf '%s\n' "Development base image: $(DEV_BASE_IMAGE)"
+	@printf '%s\n' "Compose file: $(DEV_COMPOSE_FILE)"
+	@printf '%s\n' "pnpm home: $(PNPM_HOME)"
+	@printf '%s\n' "pnpm store: $(PNPM_STORE_DIR)"
+
+worktree-doctor:
+	@$(MAKE) --no-print-directory worktree-info
+	@case "$(PNPM_HOME)" in "$(WORKTREE_ROOT)"/*) ;; *) printf '%s\n' "PNPM_HOME should stay inside this worktree: $(PNPM_HOME)"; exit 1;; esac
+	@case "$(PNPM_STORE_DIR)" in "$(WORKTREE_ROOT)"/*) ;; *) printf '%s\n' "PNPM_STORE_DIR should stay inside this worktree: $(PNPM_STORE_DIR)"; exit 1;; esac
+	@if [ "$(DEV_HOST_PORT)" = "5173" ]; then printf '%s\n' "Warning: DEV_HOST_PORT uses the default 5173; override it when another worktree is running."; fi
+	@if [ "$(HOST_PORT)" = "8080" ]; then printf '%s\n' "Warning: HOST_PORT uses the default 8080; override it when another runtime container is running."; fi
+	@if ! command -v lsof >/dev/null 2>&1; then printf '%s\n' "Port occupancy checks skipped: lsof is not available."; else \
+		if lsof -nP -iTCP:$(DEV_HOST_PORT) -sTCP:LISTEN >/dev/null 2>&1; then printf '%s\n%s\n' "Warning: DEV_HOST_PORT $(DEV_HOST_PORT) is already in use." "Suggested override: DEV_HOST_PORT=$$(( $(DEV_HOST_PORT) + 10000 )) make dev"; fi; \
+		if lsof -nP -iTCP:$(HOST_PORT) -sTCP:LISTEN >/dev/null 2>&1; then printf '%s\n%s\n' "Warning: HOST_PORT $(HOST_PORT) is already in use." "Suggested override: HOST_PORT=$$(( $(HOST_PORT) + 10000 )) make docker-run"; fi; \
+	fi
+	@printf '%s\n' "Compose config check: make worktree-compose-config"
+
+worktree-compose-config:
+	@if ! command -v docker >/dev/null 2>&1; then printf '%s\n' "Docker is not available; cannot render Compose config."; exit 1; fi
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) config
+
+clean-worktree:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) down --remove-orphans --volumes
+	@$(DOCKER) rm -f "$(RUNTIME_CONTAINER)" >/dev/null 2>&1 || true
+
+bootstrap:
+	DEV_DOCKERFILE=$(DEV_DOCKERFILE) $(COMPOSE) -f $(DEV_COMPOSE_FILE) build $(DEV_SERVICE)
+
+bootstrap-full:
+	DEV_DOCKERFILE=Dockerfile.dev.full $(COMPOSE) -f $(DEV_COMPOSE_FILE) build $(DEV_SERVICE)
+
+doctor:
+	./scripts/doctor
+
+install:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm install --frozen-lockfile
+
+lockfile-update:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm install --no-frozen-lockfile
+
+dev:
+	DEV_DOCKERFILE=$(DEV_DOCKERFILE) $(COMPOSE) -f $(DEV_COMPOSE_FILE) up $(DEV_SERVICE)
+
+dev-shell:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) bash
+
+lint:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm lint
+
+typecheck:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm typecheck
+
+test:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm test
+
+verify: doctor lint typecheck test build
+
+build:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm build
+
+preview:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm --service-ports $(DEV_SERVICE) pnpm preview --host 0.0.0.0 --port $(DEV_PORT)
+
+browser-install:
+	DEV_DOCKERFILE=$(DEV_DOCKERFILE) $(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) bash -lc "pnpm install --frozen-lockfile && pnpm browser:install"
+
+browser-smoke:
+	DEV_DOCKERFILE=$(DEV_DOCKERFILE) $(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm browser:smoke
+
+browser-smoke-production: docker-build browser-install
+	DOCKER="$(DOCKER)" IMAGE_REF="$(IMAGE_REF)" HOST_PORT="$(HOST_PORT)" CONTAINER_PORT="$(CONTAINER_PORT)" RUNTIME_CONTAINER="$(RUNTIME_CONTAINER)" DEV_COMPOSE_FILE="$(DEV_COMPOSE_FILE)" DEV_SERVICE="$(DEV_SERVICE)" DEV_DOCKERFILE="$(DEV_DOCKERFILE)" COMPOSE_PROJECT_NAME="$(COMPOSE_PROJECT_NAME)" ./scripts/browser-smoke-production
+
+format:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm format
+
+format-check:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) run --rm $(DEV_SERVICE) pnpm format:check
+
+docker-build:
+	$(DOCKER) build --build-arg BUILDER_IMAGE=$(BUILDER_IMAGE) --build-arg RUNTIME_IMAGE=$(RUNTIME_IMAGE) -t $(IMAGE_REF) .
+
+docker-run:
+	$(DOCKER) run --rm -p $(HOST_PORT):$(CONTAINER_PORT) $(IMAGE_REF)
+
+clean:
+	$(COMPOSE) -f $(DEV_COMPOSE_FILE) down --remove-orphans
+	@$(DOCKER) rm -f "$(RUNTIME_CONTAINER)" >/dev/null 2>&1 || true
+
+help:
+	@printf '%s\n' "Common commands:" "  make bootstrap  Prepare project dependencies and tooling" "  make doctor     Check the local environment" "  make lint       Run static checks" "  make test       Run automated tests" "  make verify     Run the template quality gate" "  make build      Build the project" "  make clean      Remove generated build state" "  make help       Show this command contract"

biucingcli/template_data/frontend/template/README.md

@@ -0,0 +1,146 @@
+# {{DISPLAY_NAME}}
+
+This project was generated by BiucingCLI.
+
+## Stack
+
+- React
+- TypeScript
+- Docker
+
+## Project Layout
+
+- `src/pages`: route-level pages or screens
+- `src/router`: route declarations and top-level router composition
+- `src/components`: reusable UI building blocks
+- `src/hooks`: stateful view hooks
+- `src/services`: API client, data access, and local fallback services
+- `src/config`: runtime configuration derived from Vite environment variables
+- `src/types`: shared TypeScript models
+
+## Docker Workflow
+
+```bash
+make bootstrap
+make dev
+```
+
+This starter is designed to run development, checks, and runtime packaging inside Docker by default.
+The default development image stays relatively light and installs project dependencies into a named volume on first use.
+If you want a heavier image that prewarms the pnpm store and Chromium browser cache ahead of time, run:
+
+```bash
+make bootstrap-full
+DEV_DOCKERFILE=Dockerfile.dev.full make dev
+```
+
+## Available Commands
+
+```bash
+make bootstrap
+make bootstrap-full
+make install
+make lockfile-update
+make dev
+make dev-shell
+make doctor
+make lint
+make typecheck
+make test
+make verify
+make build
+make browser-install
+make browser-smoke
+make browser-smoke-production
+make docker-build
+make docker-run
+make clean
+make help
+```
+
+## Local Frontend URL
+
+- Development server: `http://127.0.0.1:5173`
+- Runtime image: `http://127.0.0.1:8080`
+
+## Worktree Workflow
+
+This starter is safe to run from parallel Git worktrees when each worktree keeps its own identity and host ports.
+
+```bash
+make worktree-info
+make worktree-doctor
+make worktree-compose-config
+DEV_HOST_PORT=5174 make dev
+HOST_PORT=8081 make docker-run
+make clean-worktree
+```
+
+- `WORKTREE_LABEL` is derived from the worktree directory name for display.
+- `WORKTREE_ID` is derived from the current worktree path by default and can be overridden.
+- `COMPOSE_PROJECT_NAME` defaults to `{{PACKAGE_NAME}}-$(WORKTREE_ID)`, so Compose containers, networks, and volumes stay scoped to the worktree.
+- `IMAGE` defaults to the worktree slug and `TAG` defaults to `dev`, so runtime image tags do not overwrite another worktree by default.
+- `.npmrc` keeps direct `pnpm install` package-store state under `.pnpm-store` inside this worktree.
+- `make worktree-doctor` checks whether published host ports are already in use and prints suggested overrides.
+- `make worktree-compose-config` renders the current worktree's Compose config without starting containers.
+- `make clean-worktree` removes only the current worktree's Compose containers, networks, and volumes.
+
+## Direct pnpm Scripts
+
+```bash
+pnpm dev
+pnpm lint
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm test:watch
+pnpm browser:install
+pnpm browser:smoke
+pnpm format
+pnpm format:check
+```
+
+## Quality Checks
+
+- ESLint runs with the flat config format and TypeScript-aware rules.
+- Prettier keeps formatting consistent across the starter files.
+- Vitest and Testing Library provide a fast component-test baseline.
+- Playwright provides a single-command browser smoke check for localhost verification.
+- `make browser-smoke` runs the Playwright smoke check inside the Docker development image.
+- `make browser-smoke-production` builds the Nginx runtime image, waits for its container health check, and verifies the rendered app plus the `nginx` response header in Chromium.
+
+## Runtime Configuration
+
+- `VITE_API_BASE_URL`: optional base URL for backend requests.
+- When `VITE_API_BASE_URL` is not set, the starter keeps using local fallback data.
+
+## Docker Files
+
+- `Dockerfile.dev`: default lighter Node development image
+- `Dockerfile.dev.full`: optional heavier development image that prewarms pnpm dependencies and Chromium
+- `compose.dev.yaml`: local Docker development workflow
+- `Dockerfile`: production build and static runtime image
+- `nginx.conf`: SPA-friendly static serving config
+
+## Package Manager
+
+- This starter standardizes on `pnpm` via Corepack.
+- The generated `package.json` declares the expected `pnpm` and Node.js versions, and the committed `pnpm-lock.yaml` is the reproducible dependency source of truth.
+- `make install`, development images, and the production image use `--frozen-lockfile` and fail when `package.json` and `pnpm-lock.yaml` disagree.
+- After intentionally editing dependencies, run `make lockfile-update`, review both manifest and lockfile changes, then return to frozen installs.
+- Compose-scoped `node_modules`, pnpm, and Playwright cache volumes persist downloads across container runs without sharing state across worktrees.
+- Direct pnpm usage reads `.npmrc`, so package-store state stays in `.pnpm-store` under the current worktree.
+
+## Browser Smoke Check
+
+```bash
+make browser-install
+make browser-smoke
+make browser-smoke-production
+```
+
+- With the default dev image, `make browser-install` populates the shared Playwright cache volume.
+- With `Dockerfile.dev.full`, the initial build preloads that browser cache so smoke checks are ready sooner on first run.
+- `browser:smoke` starts a local Vite server on `127.0.0.1:4173`, opens Chromium, checks the starter homepage, and writes a screenshot under `test-results/`.
+- `browser-smoke-production` uses a separate Playwright configuration with no Vite server. It starts the built Nginx image in a worktree-scoped temporary container, waits for Docker health, runs Chromium from the development container against the published runtime port, verifies the Nginx response, and always removes the runtime container on exit.
+- `BUILDER_IMAGE`, `RUNTIME_IMAGE`, and `DEV_BASE_IMAGE` are overridable when CI uses an approved registry mirror. Defaults remain the official Docker Hub Node and Nginx images.

biucingcli/template_data/frontend/template/compose.dev.yaml

@@ -0,0 +1,29 @@
+services:
+  frontend-dev:
+    build:
+      context: .
+      dockerfile: ${DEV_DOCKERFILE:-Dockerfile.dev}
+      args:
+        DEV_BASE_IMAGE: ${DEV_BASE_IMAGE:-node:20-bookworm}
+    working_dir: /workspace
+    command: bash -lc "if [ ! -d node_modules/.pnpm ]; then pnpm install --frozen-lockfile; fi; pnpm dev --host 0.0.0.0 --port ${DEV_PORT:-5173} --strictPort"
+    environment:
+      CHOKIDAR_USEPOLLING: "true"
+      PNPM_STORE_DIR: /pnpm-store
+      npm_config_store_dir: /pnpm-store
+      PLAYWRIGHT_BROWSERS_PATH: /ms-playwright
+      VITE_API_BASE_URL: ${VITE_API_BASE_URL:-}
+    ports:
+      - "${DEV_HOST_PORT:-5173}:${DEV_PORT:-5173}"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      - .:/workspace
+      - frontend-node-modules:/workspace/node_modules
+      - frontend-pnpm-store:/pnpm-store
+      - frontend-playwright-cache:/ms-playwright
+
+volumes:
+  frontend-node-modules:
+  frontend-pnpm-store:
+  frontend-playwright-cache:

biucingcli/template_data/frontend/template/eslint.config.js

@@ -0,0 +1,27 @@
+import js from "@eslint/js";
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: ["dist"],
+  },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ["**/*.{ts,tsx}"],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      "react-hooks": reactHooks,
+      "react-refresh": reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
+    },
+  },
+);

biucingcli/template_data/frontend/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{DISPLAY_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

biucingcli/template_data/frontend/template/nginx.conf

@@ -0,0 +1,11 @@
+server {
+  listen 80;
+  server_name _;
+
+  root /usr/share/nginx/html;
+  index index.html;
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

biucingcli/template_data/frontend/template/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "pnpm@9.9.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "lint": "eslint .",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "browser:install": "playwright install chromium",
+    "browser:smoke": "playwright test -c playwright.smoke.config.ts",
+    "browser:smoke:production": "playwright test -c playwright.production.config.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.26.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.0",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^18.3.5",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "eslint": "^9.9.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-react-hooks": "^5.1.0-rc.0",
+    "eslint-plugin-react-refresh": "^0.4.11",
+    "globals": "^15.9.0",
+    "jsdom": "^25.0.1",
+    "playwright": "1.55.0",
+    "prettier": "^3.3.3",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.3.0",
+    "vite": "^5.4.2",
+    "vitest": "^2.0.5"
+  }
+}

biucingcli/template_data/frontend/template/playwright.production.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "playwright/test";
+
+const baseURL = process.env.PLAYWRIGHT_BASE_URL;
+
+if (!baseURL) {
+  throw new Error(
+    "PLAYWRIGHT_BASE_URL is required for production image browser tests.",
+  );
+}
+
+export default defineConfig({
+  testDir: "./tests",
+  testMatch: "production-browser-smoke.spec.ts",
+  fullyParallel: false,
+  reporter: "list",
+  use: {
+    baseURL,
+    headless: true,
+    screenshot: "only-on-failure",
+  },
+});

biucingcli/template_data/frontend/template/playwright.smoke.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from "playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  testMatch: "browser-smoke.spec.ts",
+  fullyParallel: false,
+  reporter: "list",
+  use: {
+    baseURL: "http://127.0.0.1:4173",
+    headless: true,
+    screenshot: "only-on-failure",
+  },
+  webServer: {
+    command: "pnpm exec vite --host 127.0.0.1 --port 4173 --strictPort",
+    url: "http://127.0.0.1:4173",
+    reuseExistingServer: true,
+    timeout: 30_000,
+  },
+});