Add public project guidance and repository quality checks

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,90 @@
+name: Bug report
+description: Report a reproducible problem or unexpected behavior in Huabu
+title: '[Bug]: '
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve Huabu. Please search existing issues before submitting a new report.
+
+        Do not include API keys, access tokens, private documents, personal information, or other sensitive data.
+
+  - type: checkboxes
+    id: existing-issues
+    attributes:
+      label: Existing issues
+      options:
+        - label: I searched the existing issues and did not find a report of the same problem.
+          required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Describe the behavior you observed, including any error message.
+      placeholder: Tell us what went wrong.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: What did you expect?
+      description: Describe what you were trying to do and what you expected Huabu to do instead.
+      placeholder: Tell us what should have happened.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: List the shortest sequence of steps that triggers the problem.
+      placeholder: |
+        1. Open Huabu and ...
+        2. Select ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: frequency
+    attributes:
+      label: How often does it happen?
+      options:
+        - Every time
+        - Sometimes
+        - Only once
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: system-information
+    attributes:
+      label: System information
+      description: In the desktop app, choose Help → Troubleshooting → Copy System Information, then paste the result here.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: ai-details
+    attributes:
+      label: AI-related details
+      description: Complete this only if the problem involves an AI response or edit.
+      placeholder: Include the interaction mode, agent, provider and model, selected context, relevant output, and whether proposed changes were applied. Never include an API key.
+
+  - type: textarea
+    id: screenshots-and-logs
+    attributes:
+      label: Screenshots and logs
+      description: Drag screenshots, recordings, or the relevant part of server.log here after removing sensitive information.
+
+  - type: checkboxes
+    id: sensitive-information
+    attributes:
+      label: Sensitive information
+      options:
+        - label: I reviewed this report and its attachments and removed sensitive information.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Huabu Handbook
+    url: https://microsoft.github.io/Huabu/docs/
+    about: Read the user handbook before reporting a usage question.

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint / Format / Typecheck / Test / Build / Headers
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.34.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Run quality checks
+        run: pnpm check
+        env:
+          DOCS_BASE_PATH: /Huabu/
+          DOCS_CANONICAL_ORIGIN: https://microsoft.github.io

.github/workflows/deploy-docs.yml

@@ -0,0 +1,66 @@
+name: Deploy user handbook
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'apps/docs/**'
+      - '.github/workflows/deploy-docs.yml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out Huabu
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.34.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Build handbook
+        run: pnpm --filter @huabu/docs build
+        env:
+          DOCS_BASE_PATH: /Huabu/
+          DOCS_CANONICAL_ORIGIN: https://microsoft.github.io
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload handbook artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: apps/docs/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/sync-release.yml

@@ -0,0 +1,148 @@
+name: Sync upstream release
+
+on:
+  workflow_dispatch:
+    inputs:
+      destination_tag:
+        description: 'Destination tag; leave empty to use source tag'
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+concurrency:
+  group: sync-release-${{ inputs.destination_tag }}
+  cancel-in-progress: false
+
+jobs:
+  sync-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Read latest source release
+        shell: bash
+        env:
+          SOURCE_REPO: ${{ secrets.SOURCE_REPOSITORY }}
+          SOURCE_TOKEN: ${{ secrets.SOURCE_REPO_TOKEN }}
+          REQUESTED_DEST_TAG: ${{ inputs.destination_tag }}
+        run: |
+          set -euo pipefail
+
+          GH_TOKEN="$SOURCE_TOKEN" gh release view \
+            --repo "$SOURCE_REPO" \
+            --json tagName,body,isPrerelease \
+            > source-release.json
+
+          SOURCE_TAG="$(jq -r '.tagName' source-release.json)"
+          IS_PRERELEASE="$(jq -r '.isPrerelease' source-release.json)"
+
+          DEST_TAG="$REQUESTED_DEST_TAG"
+          if [[ -z "$DEST_TAG" ]]; then
+            DEST_TAG="$SOURCE_TAG"
+          fi
+
+          for tag in "$SOURCE_TAG" "$DEST_TAG"; do
+            if [[ "$tag" == -* ]] || ! git check-ref-format "refs/tags/$tag"; then
+              echo "Invalid release tag: $tag" >&2
+              exit 1
+            fi
+          done
+
+          jq -r '.body // ""' source-release.json > release-notes.md
+
+          {
+            echo "source_tag=$SOURCE_TAG"
+            echo "dest_tag=$DEST_TAG"
+            echo "is_prerelease=$IS_PRERELEASE"
+          } >> "$GITHUB_OUTPUT"
+        id: release
+
+      - name: Download source assets
+        id: download
+        shell: bash
+        env:
+          SOURCE_REPO: ${{ secrets.SOURCE_REPOSITORY }}
+          SOURCE_TOKEN: ${{ secrets.SOURCE_REPO_TOKEN }}
+          SOURCE_TAG: ${{ steps.release.outputs.source_tag }}
+        run: |
+          set -euo pipefail
+
+          mkdir -p assets
+
+          if ! GH_TOKEN="$SOURCE_TOKEN" gh release download \
+              "$SOURCE_TAG" \
+              --repo "$SOURCE_REPO" \
+              --dir assets; then
+            echo "No downloadable assets for $SOURCE_TAG."
+          fi
+
+          asset_count="$(find assets -maxdepth 1 -type f | wc -l)"
+          if (( asset_count == 0 )); then
+            echo "Source release has no assets; skipping publish."
+            echo "has_assets=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_assets=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create or update destination release
+        if: steps.download.outputs.has_assets == 'true'
+        shell: bash
+        env:
+          DEST_REPO: ${{ github.repository }}
+          DEST_TOKEN: ${{ github.token }}
+          SOURCE_TAG: ${{ steps.release.outputs.source_tag }}
+          DEST_TAG: ${{ steps.release.outputs.dest_tag }}
+          IS_PRERELEASE: ${{ steps.release.outputs.is_prerelease }}
+        run: |
+          set -euo pipefail
+
+          TITLE="Huabu $SOURCE_TAG"
+
+          prerelease_args=()
+          if [[ "$IS_PRERELEASE" == "true" ]]; then
+            prerelease_args+=(--prerelease)
+          fi
+
+          if GH_TOKEN="$DEST_TOKEN" gh release view \
+              "$DEST_TAG" \
+              --repo "$DEST_REPO" >/dev/null 2>&1; then
+
+            echo "Updating existing release $DEST_TAG"
+
+            GH_TOKEN="$DEST_TOKEN" gh release edit \
+              "$DEST_TAG" \
+              --repo "$DEST_REPO" \
+              --title "$TITLE" \
+              --notes-file release-notes.md \
+              --prerelease="$IS_PRERELEASE"
+          else
+            echo "Creating release $DEST_TAG"
+
+            GH_TOKEN="$DEST_TOKEN" gh release create \
+              "$DEST_TAG" \
+              --repo "$DEST_REPO" \
+              --title "$TITLE" \
+              --notes-file release-notes.md \
+              "${prerelease_args[@]}"
+          fi
+
+      - name: Upload destination assets
+        if: steps.download.outputs.has_assets == 'true'
+        shell: bash
+        env:
+          DEST_REPO: ${{ github.repository }}
+          DEST_TOKEN: ${{ github.token }}
+          DEST_TAG: ${{ steps.release.outputs.dest_tag }}
+        run: |
+          set -euo pipefail
+
+          mapfile -d '' assets < <(
+            find assets -maxdepth 1 -type f -print0
+          )
+
+          GH_TOKEN="$DEST_TOKEN" gh release upload \
+            "$DEST_TAG" \
+            "${assets[@]}" \
+            --repo "$DEST_REPO" \
+            --clobber

.gitignore

@@ -315,6 +315,11 @@ FakesAssemblies/
 .ntvs_analysis.dat
 node_modules/
 
+# Huabu handbook build output
+apps/docs/.ssr/
+apps/docs/dist/
+apps/docs/tsconfig.node.tsbuildinfo
+
 # Visual Studio 6 build log
 *.plg
 

.prettierignore

@@ -0,0 +1,4 @@
+**/dist/
+**/node_modules/
+**/.ssr/
+**/*.tsbuildinfo

.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "useTabs": false,
+  "endOfLine": "lf",
+  "arrowParens": "always",
+  "plugins": ["prettier-plugin-tailwindcss"]
+}