diff --git a/.github/actions/free-disk-space/action.yaml b/.github/actions/free-disk-space/action.yaml new file mode 100644 index 0000000..8d0a87f --- /dev/null +++ b/.github/actions/free-disk-space/action.yaml @@ -0,0 +1,17 @@ +name: "Free Disk Space" +description: "Optimize available disk space by removing pre-installed software on GitHub-hosted Linux runners." + +runs: + using: "composite" + steps: + - name: Free Disk Space + if: runner.environment == 'github-hosted' && runner.os == 'Linux' + shell: bash + run: | + echo "Optimizing runner disk space..." + sudo rm -rf /usr/share/dotnet + sudo rm -rf /usr/local/lib/android + sudo rm -rf /opt/ghc + sudo rm -rf /usr/local/share/boost + sudo chown -R "$USER:$USER" "$AGENT_TOOLSDIRECTORY" 2>/dev/null || true + df -h / diff --git a/.github/actions/setup-devenv/action.yaml b/.github/actions/setup-devenv/action.yaml new file mode 100644 index 0000000..f69ea9f --- /dev/null +++ b/.github/actions/setup-devenv/action.yaml @@ -0,0 +1,55 @@ +name: "Setup Devenv" +description: "Initialize Nix and warm up the devenv shell environment." + +inputs: + cachix-cache-name: + description: "Cachix cache name." + required: false + default: "devenv" + cachix-auth-token: + description: "Cachix authorization token." + required: false + default: "" + skip-push: + description: "Skip pushing build artifacts to Cachix." + required: false + default: "true" + +runs: + using: "composite" + steps: + - name: Free Disk Space + uses: ./.github/actions/free-disk-space + + - name: Install Nix + if: runner.environment == 'github-hosted' + uses: cachix/install-nix-action@v31 + with: + nix_path: nixpkgs=channel:nixos-unstable + + - name: Install Cachix + if: runner.environment == 'github-hosted' + uses: cachix/cachix-action@v15 + with: + name: ${{ inputs.cachix-cache-name }} + authToken: ${{ inputs.cachix-auth-token }} + skipPush: ${{ inputs.skip-push }} + + - name: Install Devenv CLI + shell: bash + run: | + if [ -d "$HOME/.nix-profile/bin" ]; then + echo "$HOME/.nix-profile/bin" >> "$GITHUB_PATH" + export PATH="$HOME/.nix-profile/bin:$PATH" + fi + if ! command -v devenv >/dev/null 2>&1; then + nix profile add --accept-flake-config nixpkgs#devenv || nix profile install --accept-flake-config tarball+https://install.devenv.sh/latest + if [ -d "$HOME/.nix-profile/bin" ]; then + echo "$HOME/.nix-profile/bin" >> "$GITHUB_PATH" + export PATH="$HOME/.nix-profile/bin:$PATH" + fi + fi + + - name: Warm Up Devenv Environment + shell: bash + run: devenv --no-tui shell -- echo "devenv ready" diff --git a/.github/actions/step-summary/action.yaml b/.github/actions/step-summary/action.yaml new file mode 100644 index 0000000..1a56445 --- /dev/null +++ b/.github/actions/step-summary/action.yaml @@ -0,0 +1,58 @@ +name: "Step Summary" +description: "Render a standardized execution summary table to GITHUB_STEP_SUMMARY." + +inputs: + title: + description: "Summary table header title." + required: false + default: "Build & Test Summary" + jobs: + description: "Multiline list of pipe-delimited Step Name|outcome pairs." + required: true + footer: + description: "Optional markdown footer text." + required: false + default: "" + +runs: + using: "composite" + steps: + - name: Write Step Summary + shell: bash + run: | + { + echo "## ${{ inputs.title }}" + echo "" + if [ -n "${{ github.event.pull_request.number }}" ]; then + echo "**Pull Request**: #${{ github.event.pull_request.number }} - ${{ github.event.pull_request.title }}" + echo "**Branch**: \`${{ github.head_ref }}\` → \`${{ github.base_ref }}\`" + echo "" + fi + echo "| Step | Status |" + echo "| :--- | :---: |" + while IFS='|' read -r step outcome; do + [ -z "$step" ] && continue + case "$outcome" in + success) + status="✅ Passed" + ;; + failure) + status="❌ Failed" + ;; + cancelled) + status="⛔ Cancelled" + ;; + skipped) + status="⏭️ Skipped" + ;; + *) + status="ℹ️ $outcome" + ;; + esac + echo "| $step | $status |" + done <<< "${{ inputs.jobs }}" + if [ -n "${{ inputs.footer }}" ]; then + echo "" + echo "${{ inputs.footer }}" + fi + } >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..1e35e91 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,72 @@ +name: CI + +on: + push: + branches: + - trunk + pull_request: + branches: + - trunk + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +permissions: + contents: read + +jobs: + verify: + name: Verify Toolchain & Build + runs-on: + group: tars-cloud + labels: [self-hosted, nixos] + steps: + - name: Checkout Source Code + id: checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Optimize Runner Disk Space + id: disk_space + uses: ./.github/actions/free-disk-space + + - name: Initialize Devenv Toolchain + id: devenv_setup + uses: ./.github/actions/setup-devenv + + - name: Run Devenv Test Suite + id: test + run: devenv test + + - name: Validate Zola Syntax & Links + id: zola_check + run: devenv --no-tui shell -- zola check + + - name: Compile Site & Generate Search Index + id: build + run: devenv --no-tui shell -- zola build && devenv --no-tui shell -- pagefind --site public + + - name: Verify Routing & Crawler Directives + id: verify_assets + run: | + test -f public/CNAME + test "$(cat public/CNAME)" = "tars-cloud.ai" + test -f public/robots.txt + grep -q "https://tars-cloud.ai/sitemap.xml" public/robots.txt + test -f public/pagefind/pagefind.js + + - name: Render Summary Table + if: always() + uses: ./.github/actions/step-summary + with: + title: "CI Verification Summary" + jobs: | + Checkout Source Code|${{ steps.checkout.outcome }} + Optimize Runner Disk Space|${{ steps.disk_space.outcome }} + Initialize Devenv Toolchain|${{ steps.devenv_setup.outcome }} + Run Devenv Test Suite|${{ steps.test.outcome }} + Validate Zola Syntax & Links|${{ steps.zola_check.outcome }} + Compile Site & Generate Search Index|${{ steps.build.outcome }} + Verify Routing & Crawler Directives|${{ steps.verify_assets.outcome }} diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..dabadf3 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,82 @@ +name: Deploy + +on: + push: + branches: + - trunk + +concurrency: + group: pages-deploy + cancel-in-progress: false + +permissions: + contents: read + pages: write + id-token: write + +jobs: + deploy: + name: Build & Publish GitHub Pages + runs-on: + group: tars-cloud + labels: [self-hosted, nixos] + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Checkout Source Code + id: checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Optimize Runner Disk Space + id: disk_space + uses: ./.github/actions/free-disk-space + + - name: Initialize Devenv Toolchain + id: devenv_setup + uses: ./.github/actions/setup-devenv + + - name: Compile Production Site & Search Index + id: build + run: devenv --no-tui shell -- zola build && devenv --no-tui shell -- pagefind --site public + + - name: Verify Routing & Crawler Directives + id: verify_assets + run: | + test -f public/CNAME + test "$(cat public/CNAME)" = "tars-cloud.ai" + test -f public/robots.txt + grep -q "https://tars-cloud.ai/sitemap.xml" public/robots.txt + test -f public/pagefind/pagefind.js + + - name: Configure GitHub Pages + id: pages_config + uses: actions/configure-pages@v5 + + - name: Upload Pages Artifact + id: upload_pages + uses: actions/upload-pages-artifact@v3 + with: + path: public + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + + - name: Render Summary Table + if: always() + uses: ./.github/actions/step-summary + with: + title: "Pages Deployment Summary" + jobs: | + Checkout Source Code|${{ steps.checkout.outcome }} + Optimize Runner Disk Space|${{ steps.disk_space.outcome }} + Initialize Devenv Toolchain|${{ steps.devenv_setup.outcome }} + Compile Production Site & Search Index|${{ steps.build.outcome }} + Verify Routing & Crawler Directives|${{ steps.verify_assets.outcome }} + Configure GitHub Pages|${{ steps.pages_config.outcome }} + Upload Pages Artifact|${{ steps.upload_pages.outcome }} + Deploy to GitHub Pages|${{ steps.deployment.outcome }} + footer: "🚀 Successfully published to [https://tars-cloud.ai](https://tars-cloud.ai)" diff --git a/.gitignore b/.gitignore index d2104b9..4b4fb1e 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,14 @@ devenv.local.yaml # pre-commit .pre-commit-config.yaml + +# Build outputs +public/ +.pagefind/ + +# Cache directories +.cache/ + +# Operating system files +.DS_Store +Thumbs.db diff --git a/.versionrc b/.versionrc new file mode 100644 index 0000000..e5f8387 --- /dev/null +++ b/.versionrc @@ -0,0 +1,47 @@ +# .versionrc - Conventional commit configuration for convco +--- +header: | + # Changelog +types: + - type: feat + section: Features + hidden: false + - type: fix + section: Fixes + hidden: false + - type: perf + section: Performance + hidden: false + - type: docs + section: Documentation + hidden: true + - type: build + section: Other + hidden: true + - type: chore + section: Other + hidden: true + - type: ci + section: Other + hidden: true + - type: style + section: Other + hidden: true + - type: refactor + section: Other + hidden: true + - type: test + section: Other + hidden: true +preMajor: false +commitUrlFormat: 'https://github.com/tars-cloud/website/commit/{{hash}}' +compareUrlFormat: 'https://github.com/tars-cloud/website/compare/{{previousTag}}...{{currentTag}}' +issueUrlFormat: 'https://github.com/tars-cloud/website/issues/{{issue}}' +releaseCommitMessageFormat: 'chore(release): {{currentTag}}' +issuePrefixes: + - '#' +scopeRegex: '[[:alnum:]]+(?:[-_/][[:alnum:]]+)*' +lineLength: 80 +wrapDisabled: false +linkCompare: true +linkReferences: true diff --git a/README.md b/README.md index f13af8d..14528ee 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,57 @@ -# website -The TARS Cloud website +# TARS Cloud Website + +The sovereign public portal, technical documentation hub, and binary distribution catalog for TARS Cloud, hosted at [https://tars-cloud.ai](https://tars-cloud.ai). + +## Architecture + +- **Static Compiler**: [Zola](https://www.getzola.org/) (v0.23.4) provides native Rust CommonMark rendering and Tera templating without Node.js runtime overhead. +- **Styling Pipeline**: [Tailwind CSS v4](https://tailwindcss.com/) (v4.3.3) standalone CLI binary compiles utility styles directly. +- **Search Engine**: [Pagefind](https://pagefind.app/) (v1.5.2) generates offline WebAssembly search indexes directly from compiled HTML assets. +- **Release Automation**: [convco](https://convco.github.io/) (v0.6.3) enforces Conventional Commits and generates changelogs. +- **Reproducible Toolchain**: [devenv](https://devenv.sh/) with Nix flakes provisions identical binaries locally and in CI. +- **Zero Node Footprint**: Zero `package.json`, zero npm packages, and zero `node_modules/` dependencies. + +## Prerequisites + +- [Nix](https://nixos.org/download.html) package manager with Flakes enabled. +- [devenv](https://devenv.sh/getting-started/) CLI installed. + +## Quickstart + +Enter the reproducible development shell: + +```bash +devenv shell +``` + +Once inside the shell, all required tools and workflow scripts are available. + +## Command Reference + +| Command | Description | Underlying Execution | +| :--- | :--- | :--- | +| `build` | Compiles site assets and constructs Pagefind search index | `zola build && pagefind --site public` | +| `check` | Validates markdown links, anchors, and taxonomy paths | `zola check` | +| `serve` | Launches local development server with draft previews | `zola serve --drafts` | +| `devenv test` | Headless verification suite running syntax and build checks | `zola check && zola build` | +| `convco check` | Validates commit messages against conventional commit format | `convco check ` | + +## Project Structure + +``` +├── .github/ +│ ├── actions/ # Reusable GitHub Actions composite actions +│ └── workflows/ # CI and deployment workflows +├── content/ # Markdown content pages and sections +├── static/ # Static assets copied directly to public/ +├── templates/ # Tera templates for layout and pages +├── config.toml # Authoritative Zola site configuration +├── devenv.nix # Nix package manifest and developer scripts +├── devenv.yaml # Nixpkgs channel input pinning +└── .versionrc # Conventional commit schema configuration +``` + +## Continuous Integration & Deployment + +- **Validation**: `.github/workflows/ci.yml` runs link checks, devenv test suites, and build validation on push and pull requests targeting `trunk`. +- **Deployment**: `.github/workflows/deploy.yml` compiles production static assets on push to `trunk` and publishes to GitHub Pages via enterprise self-hosted runners (`[self-hosted, tars-cloud]`). diff --git a/config.toml b/config.toml new file mode 100644 index 0000000..091228c --- /dev/null +++ b/config.toml @@ -0,0 +1,31 @@ +# Authoritative configuration for TARS Cloud Website (https://tars-cloud.ai) +base_url = "https://tars-cloud.ai" +title = "TARS Cloud" +description = "Official portal, documentation hub, and download distribution center for TARS Cloud." +default_language = "en" + +build_search_index = false +compile_sass = false +generate_feeds = true +feed_filenames = ["atom.xml"] + +taxonomies = [ + { name = "tags", feed = true }, + { name = "categories", feed = true } +] + +[extra] +repository_url = "https://github.com/tars-cloud/website" +docs_url = "https://tars-cloud.ai/docs" +downloads_url = "https://tars-cloud.ai/downloads" +contact_email = "cooper@tars-cloud.ai" + +theme_mode = "tactical-cyberpunk" +accent_cyan = "#00f3ff" +accent_amber = "#ffb700" +bg_dark = "#0a0d12" +bg_panel = "#121820" +enable_scanlines = true +scanline_opacity = 0.08 +terminal_font = "JetBrains Mono, monospace" +body_font = "Inter, sans-serif" diff --git a/devenv.nix b/devenv.nix index 9d22604..03c50b8 100644 --- a/devenv.nix +++ b/devenv.nix @@ -1,46 +1,36 @@ -{ pkgs, lib, config, inputs, ... }: - { - # https://devenv.sh/basics/ - env.GREET = "devenv"; - - # https://devenv.sh/packages/ - packages = [ pkgs.git ]; - - # https://devenv.sh/languages/ - # languages.rust.enable = true; - - # https://devenv.sh/processes/ - # processes.dev.exec = "${lib.getExe pkgs.watchexec} -n -- ls -la"; - - # https://devenv.sh/services/ - # services.postgres.enable = true; + pkgs, + lib, + config, + inputs, + ... +}: - # https://devenv.sh/scripts/ - scripts.hello.exec = '' - echo hello from $GREET - ''; +{ + packages = [ + pkgs.zola + pkgs.tailwindcss_4 + pkgs.pagefind + pkgs.convco + pkgs.git + pkgs.curl + pkgs.jq + ]; + + scripts.build.exec = "zola build && pagefind --site public"; + scripts.check.exec = "zola check"; + scripts.serve.exec = "zola serve --drafts"; - # https://devenv.sh/basics/ enterShell = '' - hello # Run scripts directly - git --version # Use packages + echo "TARS Cloud Development Environment" + echo "Available commands: build, check, serve, devenv test" + zola --version + pagefind --version + convco --version ''; - # https://devenv.sh/tasks/ - # tasks = { - # "myproj:setup".exec = "mytool build"; - # "devenv:enterShell".after = [ "myproj:setup" ]; - # }; - - # https://devenv.sh/tests/ enterTest = '' - echo "Running tests" - git --version | grep --color=auto "${pkgs.git.version}" + zola check + zola build ''; - - # https://devenv.sh/git-hooks/ - # git-hooks.hooks.shellcheck.enable = true; - - # See full reference at https://devenv.sh/reference/options/ } diff --git a/devenv.yaml b/devenv.yaml index 3dcab58..68616a4 100644 --- a/devenv.yaml +++ b/devenv.yaml @@ -2,17 +2,3 @@ inputs: nixpkgs: url: github:cachix/devenv-nixpkgs/rolling - -# If you're using non-OSS software, you can set allow_unfree to true. -# allow_unfree: true - -# If you're not willing to allow unsupported packages: -# allow_unsupported_system: false - -# If you're willing to use a package that's vulnerable -# permitted_insecure_packages: -# - "openssl-1.1.1w" - -# If you have more than one devenv you can merge them -#imports: -# - ./backend diff --git a/static/CNAME b/static/CNAME new file mode 100644 index 0000000..03615af --- /dev/null +++ b/static/CNAME @@ -0,0 +1 @@ +tars-cloud.ai diff --git a/static/robots.txt b/static/robots.txt new file mode 100644 index 0000000..967a89c --- /dev/null +++ b/static/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://tars-cloud.ai/sitemap.xml diff --git a/templates/.gitkeep b/templates/.gitkeep new file mode 100644 index 0000000..e69de29