{"id":43089823,"url":"https://github.com/mac9sb/server","last_synced_at":"2026-01-31T16:03:18.365Z","repository":{"id":334572947,"uuid":"1140683962","full_name":"mac9sb/server","owner":"mac9sb","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-26T04:03:57.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T09:16:51.254Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Pkl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mac9sb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-01-23T16:06:35.000Z","updated_at":"2026-01-26T04:04:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mac9sb/server","commit_stats":null,"previous_names":["mac9sb/server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mac9sb/server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac9sb%2Fserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac9sb%2Fserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac9sb%2Fserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac9sb%2Fserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mac9sb","download_url":"https://codeload.github.com/mac9sb/server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mac9sb%2Fserver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28947567,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T14:26:55.697Z","status":"ssl_error","status_checked_at":"2026-01-31T14:26:52.545Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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-01-31T16:03:14.642Z","updated_at":"2026-01-31T16:03:18.360Z","avatar_url":"https://github.com/mac9sb.png","language":"Pkl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Developer Server\n\nAn arc project for hosting applications and static sites.\n\n## Directory Structure\n\n### `sites/`\n\nAll hosted applications and static sites. This unified directory contains both dynamic server applications and static site generators.\n\n#### Server Applications\n\nServer applications built with Swift and Hummingbird. Each subdirectory contains a `Web/` directory with its own `Package.swift`.\n\n**Working with apps:**\n\n```sh\ncd sites/\u003capp-name\u003e/Web\nswift build -c release\n```\n\nApps are configured in `Arc.swift` with `.service()` and require a port assignment.\n\n#### Static Sites\n\nStatic sites built with Swift and WebUI. Each subdirectory is a standalone site generator with its own `Package.swift`.\n\n**Working with static sites:**\n\n```sh\ncd sites/\u003csite-name\u003e\nswift run\n```\n\nThis generates the site into a `.output` directory. Sites are configured in `Arc.swift` with `.page()`.\n\n### `tooling/`\n\nShared tooling and utilities used across projects:\n\n- **arc** - Server orchestration and proxy\n- **web-ui** - HTML generation framework\n- **fluent-gen** - Fluent ORM macro package\n- **list** - Enhanced `ls` command-line tool\n\n### `Arc.swift`\n\nArc server configuration defining all hosted sites and services. This file uses the ArcDescription DSL to configure routing, domains, and process management.\n\n### `config.pkl`\n\nLegacy Pkl configuration (deprecated in favor of `Arc.swift`).\n\n## Running the Server\n\n```sh\narc run                     # Start in foreground\narc run --background        # Start in background\narc status                  # Check running processes and site health\narc status \u003cproject-name\u003e   # View detailed status for a specific project\narc logs                    # View logs\narc stop                    # Stop running servers\n```\n\nThe server proxies requests based on domain configuration in `Arc.swift`.\n\n## Development Workflows\n\n### Command Line\n\n#### Build All Projects\n\n```sh\n./scripts/build-all.sh\n```\n\nThis builds all tooling and sites in the correct dependency order.\n\n#### Build Individual Projects\n\n```sh\n# Build Arc\ncd tooling/arc \u0026\u0026 swift build -c release\n\n# Build WebUI\ncd tooling/web-ui \u0026\u0026 swift build -c release\n\n# Build Guest List\ncd sites/guest-list/Web \u0026\u0026 swift build -c release\n\n# Generate Portfolio\ncd sites/portfolio \u0026\u0026 swift run\n```\n\n#### Run Tests\n\n```sh\n# Test Arc\ncd tooling/arc \u0026\u0026 swift test\n\n# Test WebUI\ncd tooling/web-ui \u0026\u0026 swift test\n\n# Test Guest List\ncd sites/guest-list/Web \u0026\u0026 swift test\n```\n\n### Xcode Development\n\nThis monorepo includes a unified Xcode workspace for IDE-based development.\n\n#### Open Workspace\n\n```sh\nopen Developer.xcworkspace\n```\n\n**Important:** Always open the workspace, not individual `Package.swift` files.\n\n#### Available Schemes\n\n- **Arc** - Run Arc server in foreground with keep-awake\n- **Arc (Background)** - Run Arc in background mode\n- **GuestList** - Run Guest List app directly (bypass Arc)\n- **Portfolio (Generate)** - Generate portfolio static site\n- **WebUI CLI** - Test WebUI command-line interface\n\nEach scheme is pre-configured with the correct working directory and arguments.\n\n#### Quick Start\n\n1. Open `Developer.xcworkspace`\n2. Select \"Arc\" scheme from scheme picker\n3. Press `⌘R` to run\n4. Arc starts all configured sites\n5. Check Xcode console for output\n\nFor detailed Xcode setup, debugging tips, and scheme documentation, see [docs/XCODE_SETUP.md](docs/XCODE_SETUP.md).\n\n## File Watching\n\nArc automatically watches for changes and reloads as needed:\n\n- **Config changes** - Modifications to `Arc.swift` trigger a full configuration reload\n- **App binaries** - Rebuilt executables in `sites/` are detected and the corresponding process is restarted\n- **Static outputs** - Regenerated `.output` directories in `sites/` are picked up immediately\n\n## Git Submodules\n\nAll major components are git submodules:\n\n```sh\n# Initialize submodules after clone\ngit submodule update --init --recursive\n\n# Update all submodules to latest\ngit submodule update --remote\n\n# Update specific submodule\ncd tooling/arc \u0026\u0026 git pull origin main\n```\n\n## Git Hooks (build + test gate)\n\nInstall hooks for the root repo and all submodules:\n\n```sh\n./scripts/install-githooks.sh\n```\n\nHooks will run validation for the root repo, and `swift format lint`, `swift test`, and `swift build -c release` for every repo with a `Package.swift` before allowing a commit or push.\n\n\u003e [!NOTE] \n\u003e Tap hooks are currently disabled.\n\n## Documentation\n\n- [Xcode Setup Guide](docs/XCODE_SETUP.md) - IDE development workflow\n- [CLI UX Best Practices](docs/CLI_UX.md) - Command-line interface standards\n- [Logging Best Practices](docs/LOGGING.md) - Structured logging guidelines\n\n## Project Standards\n\n### CLI Tools\nAll command-line tools use [Noora](https://noora.tuist.dev) for consistent terminal output. See [docs/CLI_UX.md](docs/CLI_UX.md) for guidelines.\n\n### Logging\nAll projects use [swift-log](https://github.com/apple/swift-log) for structured logging. No custom abstractions. See [docs/LOGGING.md](docs/LOGGING.md) for best practices.\n\n### Code Style\n- Swift 6.0+ with strict concurrency checking\n- Follow Swift API Design Guidelines\n- Use SwiftFormat for consistent formatting\n- Comprehensive documentation comments\n\n## Architecture\n\n```\nDeveloper/\n├── sites/                    # All hosted sites\n│   ├── guest-list/          # Server application\n│   │   └── Web/            # Hummingbird app\n│   └── portfolio/          # Static site generator\n├── tooling/                 # Shared tools\n│   ├── arc/                # Server orchestration\n│   ├── web-ui/             # HTML generation\n│   ├── fluent-gen/         # ORM macros\n│   └── list/               # CLI utilities\n├── scripts/                 # Build and utility scripts\n├── docs/                    # Documentation\n├── Arc.swift               # Server configuration\n└── Developer.xcworkspace/  # Xcode workspace\n```\n\n## Contributing\n\n1. Check out a branch\n2. Make changes in appropriate submodule\n3. Test locally with `swift test`\n4. Format code with `swift format`\n5. Commit submodule changes first\n6. Update submodule reference in monorepo\n7. Push and create PR\n\n## License\n\nSee individual projects for license information.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmac9sb%2Fserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmac9sb%2Fserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmac9sb%2Fserver/lists"}