commit e8a0c486587d565c233320257a9d6b24e8febd40 Author: Huxley Date: Sat Apr 25 17:18:16 2026 +0000 Initialize project skeleton with CLI and documentation Add initial project structure including: - Go module with Cobra CLI dependency - Root command and main entrypoint - Basic documentation (README, AGENTS.md, architecture, decisions, development, roadmap) - Configuration example and gitignore - Tool version management with mise - Comprehensive project rules and conventions diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ab2258a --- /dev/null +++ b/.gitignore @@ -0,0 +1,39 @@ +# If you prefer the allow list template instead of the deny list, see community template: +# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore +# +# Binaries for programs and plugins +*.exe +*.exe~ +*.dll +*.so +*.dylib + +# Test binary, built with `go test -c` +*.test + +# Code coverage profiles and other test artifacts +*.out +coverage.* +*.coverprofile +profile.cov + +# Dependency directories (remove the comment below to include it) +# vendor/ + +# Go workspace file +go.work +go.work.sum + +# env file +.env + +# Editor/IDE +# .idea/ +# .vscode/ + +# Mise +mise.local.toml + +# MyGO configuration +# Tracking config.example.yaml in version control +config.yaml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..05cc839 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,54 @@ +# AGENTS.md — MyGO Backend + +## Project Essentials + +- Module: `github.com/dhao2001/mygo`, Go 1.26.2 +- WebDisk (cloud drive) backend; roadmap in `docs/roadmap.md` +- CLI framework: `github.com/spf13/cobra` +- Go version pinned in `mise.toml` + +## Agent Workflow + +1. Read the task +2. Read relevant `docs/` files for context +3. Explore existing code before writing new code +4. Implement following the conventions below +5. Verify: `go vet ./... && go test ./...` +6. Update `docs/roadmap.md`, `docs/decisions.md`, or `docs/architecture.md` if anything changed + +## Go Conventions + +- **Format**: `go fmt ./...` before every commit +- **Imports**: stdlib / third-party / internal, blank-line separated +- **Errors**: wrap with `fmt.Errorf("context: %w", err)` +- **Context**: first param in I/O, storage, lifecycle funcs +- **Exported names**: doc-commented +- **`init()`**: only in cobra cmd files for flag registration +- **`cmd/`** is thin; business logic goes in `internal/` + +## Documentation + +| File | Read Before | Update After | +|------|-------------|--------------| +| `docs/architecture.md` | Adding new packages | Adding new packages | +| `docs/decisions.md` | Making technical decisions | Making technical decisions | +| `docs/roadmap.md` | Every task | Completing a feature | +| `docs/development.md` | Build/test/debug setup | Changing workflow | + +## Commands + +```bash +go build ./... # build all packages +go test ./... # all tests +go vet ./... # static analysis +go fmt ./... # format +go mod tidy # clean deps after add/remove +``` + +## DO / DON'T + +- DO put business logic in `internal/`, keep `cmd/` thin +- DO write all code, comments, and documentation in English +- DON'T read `go.sum` entirely into context — use `grep` or other tools to search specific patterns if needed +- DON'T skip `go vet ./...` before finishing work +- DON'T commit without explicit user request diff --git a/README.md b/README.md new file mode 100644 index 0000000..f064a81 --- /dev/null +++ b/README.md @@ -0,0 +1,48 @@ +# MyGO + +MyGO is a WebDisk (cloud drive) server, written in Go. + +**Current status**: pre-alpha — project skeleton with no core functionality implemented yet. + +--- + +## Roadmap + +### v0 + +- [ ] CLI configuration management (`mygo config`) +- [ ] User authentication (JWT) +- [ ] File upload / download / management (HTTP API) +- [ ] Admin endpoints +- [ ] WebDAV support + +### Future + +- [ ] Image server +- [ ] Pastebin & code snippet editing in sharing +- [ ] S3 storage backend +- [ ] Nextcloud-compatible API + +--- + +## CLI + +`mygo` is the backend entrypoint with these subcommands: + +| Command | Description | +|---------|-------------| +| `mygo serve` | Start the backend server | +| `mygo config` | Manage instance configuration | +| `mygo status` | Show server status | + +--- + +## Frontend + +The frontend uses React + TypeScript and communicates with the backend via HTTP API. Frontend source is maintained in a separate repository. + +--- + +## Development + +See `docs/development.md` for build and test workflows. See `AGENTS.md` for behavioral conventions. diff --git a/cmd/root.go b/cmd/root.go new file mode 100644 index 0000000..c210ad7 --- /dev/null +++ b/cmd/root.go @@ -0,0 +1,28 @@ +package cmd + +import ( + "os" + + "github.com/spf13/cobra" +) + +// rootCmd represents the base command when called without any subcommands +var rootCmd = &cobra.Command{ + Use: "mygo { serve | config | status }", + Short: "MyGO server application", + Long: `MyGO is a WebDisk (Cloud Drive) server. +This is the server (backend) application for MyGO.`, +} + +// Execute adds all child commands to the root command and sets flags appropriately. +// This is called by main.main(). It only needs to happen once to the rootCmd. +func Execute() { + err := rootCmd.Execute() + if err != nil { + os.Exit(1) + } +} + +func init() { + cobra.OnInitialize() +} diff --git a/config.example.yaml b/config.example.yaml new file mode 100644 index 0000000..93860d9 --- /dev/null +++ b/config.example.yaml @@ -0,0 +1,3 @@ +server: + host: 0.0.0.0 + port: 10086 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6c6e586 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# Docs + +| File | Content | +|------|---------| +| `architecture.md` | Module layout, package boundaries | +| `decisions.md` | Technical decisions (ADR) | +| `roadmap.md` | Feature progress and status | +| `development.md` | Build, test, debug workflow | diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..6b79e96 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,22 @@ +# Architecture + +## Code Layout + +``` +main.go — entrypoint, calls cmd.Execute() +cmd/ — cobra commands (root + subcommands) +internal/ — private application packages +docs/ — project documentation +``` + +## Packages + +| Package | Purpose | Status | +|---------|---------|--------| +| `cmd` | CLI command definitions | ✅ skeleton | +| `internal/config` | Configuration loading and parsing | ⬜ planned | +| `internal/controllers` | HTTP request handlers | ⬜ planned | +| `internal/auth` | Authentication (JWT) | ⬜ planned | +| `internal/storage` | File storage abstraction | ⬜ planned | + +Add new rows as packages are created. diff --git a/docs/decisions.md b/docs/decisions.md new file mode 100644 index 0000000..52aa9e8 --- /dev/null +++ b/docs/decisions.md @@ -0,0 +1,19 @@ +# Technical Decisions + +Record significant technical decisions as they are made. Use the format below. + +## Template + +``` +## YYYY-MM-DD: Title + +**Context**: Why this decision was needed. + +**Decision**: What was decided. + +**Consequences**: What this means for the project. +``` + +## Decisions + +*(None yet. Add entries as decisions are made.)* diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..2e6cc43 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,37 @@ +# Development + +## Prerequisites + +- Go 1.26.2 (pinned in `mise.toml`) +- `mise` (https://mise.jdx.dev) — run `mise install` to install toolchain + +## Build + +```bash +go build ./... +go build -o mygo . +``` + +## Test + +```bash +go test ./... +go test -v -run TestName ./internal/... +``` + +## Lint & Format + +```bash +go vet ./... +go fmt ./... +``` + +## Config + +Server config is in `config.yaml` (symlink to `config.example.yaml` in development environment). + +``` +server: + host: 0.0.0.0 + port: 10086 +``` diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..29a811b --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,24 @@ +# Roadmap + +See `README.md` for high-level feature list. This file tracks detailed progress. + +## v0 + +| Feature | Status | Notes | +|---------|--------|-------| +| CLI config management | ⬜ planned | | +| JWT authentication | ⬜ planned | | +| File upload/download/manage APIs | ⬜ planned | | +| Admin endpoints | ⬜ planned | | +| WebDAV | ⬜ planned | | + +## Future + +| Feature | Status | Notes | +|---------|--------|-------| +| Image server | ⬜ planned | | +| Pastebin & code snippets | ⬜ planned | | +| S3 storage backend | ⬜ planned | | +| Nextcloud-compatible API | ⬜ planned | | + +Update status after completing related work. diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..5fa65c8 --- /dev/null +++ b/go.mod @@ -0,0 +1,10 @@ +module github.com/dhao2001/mygo + +go 1.26.2 + +require github.com/spf13/cobra v1.10.2 + +require ( + github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/spf13/pflag v1.0.10 // indirect +) diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..ef5d78d --- /dev/null +++ b/go.sum @@ -0,0 +1,11 @@ +github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= +github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= +github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= +github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= +github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk= +github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= diff --git a/main.go b/main.go new file mode 100644 index 0000000..96d0297 --- /dev/null +++ b/main.go @@ -0,0 +1,7 @@ +package main + +import "github.com/dhao2001/mygo/cmd" + +func main() { + cmd.Execute() +} diff --git a/mise.toml b/mise.toml new file mode 100644 index 0000000..966f88a --- /dev/null +++ b/mise.toml @@ -0,0 +1,2 @@ +[tools] +go = "1.26.2"