diff --git a/core-test b/core-test new file mode 100755 index 00000000..7a211f99 Binary files /dev/null and b/core-test differ diff --git a/go.mod b/go.mod index 242bca57..04725dc6 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,6 @@ go 1.25.5 require ( github.com/Snider/Borg v0.1.0 github.com/getkin/kin-openapi v0.133.0 - github.com/host-uk/core-gui v0.0.0-20260131214111-6e2460834a87 github.com/leaanthony/debme v1.2.1 github.com/leaanthony/gosod v1.0.4 github.com/minio/selfupdate v0.6.0 @@ -58,6 +57,7 @@ require ( github.com/tidwall/match v1.2.0 // indirect github.com/tidwall/pretty v1.2.1 // indirect github.com/tidwall/sjson v1.2.5 // indirect + github.com/ugorji/go/codec v1.3.0 // indirect github.com/wI2L/jsondiff v0.7.0 // indirect github.com/woodsbury/decimal128 v1.4.0 // indirect github.com/xanzy/ssh-agent v0.3.3 // indirect diff --git a/go.sum b/go.sum index f17621d1..1402b11e 100644 --- a/go.sum +++ b/go.sum @@ -59,8 +59,6 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8= github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE= -github.com/host-uk/core-gui v0.0.0-20260131214111-6e2460834a87 h1:gCdRVNxL1GpKhiYhtqJ60xm2ML3zU/UbYR9lHzlAWb8= -github.com/host-uk/core-gui v0.0.0-20260131214111-6e2460834a87/go.mod h1:yOBnW4of0/82O6GSxFl2Pxepq9yTlJg2pLVwaU9cWHo= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 h1:BQSFePA1RWJOlocH6Fxy8MmwDt+yVQYULKfN0RoTN8A= diff --git a/internal/cmd/help/cmd.go b/internal/cmd/help/cmd.go new file mode 100644 index 00000000..dcb8073c --- /dev/null +++ b/internal/cmd/help/cmd.go @@ -0,0 +1,66 @@ +package help + +import ( + "fmt" + + "github.com/host-uk/core/pkg/cli" + "github.com/host-uk/core/pkg/help" +) + +func init() { + cli.RegisterCommands(AddHelpCommands) +} + +func AddHelpCommands(root *cli.Command) { + var searchFlag string + + helpCmd := &cli.Command{ + Use: "help [topic]", + Short: "Display help documentation", + Run: func(cmd *cli.Command, args []string) { + catalog := help.DefaultCatalog() + + if searchFlag != "" { + results := catalog.Search(searchFlag) + if len(results) == 0 { + fmt.Println("No topics found.") + return + } + fmt.Println("Search Results:") + for _, res := range results { + fmt.Printf(" %s - %s\n", res.Topic.ID, res.Topic.Title) + } + return + } + + if len(args) == 0 { + topics := catalog.List() + fmt.Println("Available Help Topics:") + for _, t := range topics { + fmt.Printf(" %s - %s\n", t.ID, t.Title) + } + return + } + + topic, err := catalog.Get(args[0]) + if err != nil { + fmt.Printf("Error: %v\n", err) + return + } + + renderTopic(topic) + }, + } + + helpCmd.Flags().StringVarP(&searchFlag, "search", "s", "", "Search help topics") + root.AddCommand(helpCmd) +} + +func renderTopic(t *help.Topic) { + // Simple ANSI rendering for now + // Use explicit ANSI codes or just print + fmt.Printf("\n\033[1;34m%s\033[0m\n", t.Title) // Blue bold title + fmt.Println("----------------------------------------") + fmt.Println(t.Content) + fmt.Println() +} diff --git a/internal/cmd/updater/updater.go b/internal/cmd/updater/updater.go index 69929c4a..f364fa8b 100644 --- a/internal/cmd/updater/updater.go +++ b/internal/cmd/updater/updater.go @@ -11,6 +11,9 @@ import ( "golang.org/x/mod/semver" ) +// PkgVersion is set via ldflags +var PkgVersion = "dev" + // Version holds the current version of the application. // It is set at build time via ldflags or fallback to the version in package.json. var Version = PkgVersion diff --git a/internal/variants/full.go b/internal/variants/full.go index 0232c70a..861ea7b2 100644 --- a/internal/variants/full.go +++ b/internal/variants/full.go @@ -41,5 +41,6 @@ import ( _ "github.com/host-uk/core/internal/cmd/updater" _ "github.com/host-uk/core/internal/cmd/vm" _ "github.com/host-uk/core/internal/cmd/workspace" + _ "github.com/host-uk/core/internal/cmd/help" _ "github.com/host-uk/core/pkg/build/buildcmd" ) diff --git a/issues.json b/issues.json new file mode 100644 index 00000000..7b21d3d6 --- /dev/null +++ b/issues.json @@ -0,0 +1 @@ +[{"body":"Parent: #133\n\n**Complexity: Low** - Good for parallel work\n\n## Task\nAdd `core help` command that displays help topics in the terminal.\n\n## Commands\n\n```bash\n# List all help topics\ncore help\n\n# Show specific topic\ncore help getting-started\n\n# Show specific section\ncore help getting-started#installation\n\n# Search help\ncore help --search \"workspace\"\ncore help -s \"config\"\n```\n\n## Implementation\n\n```go\n// internal/cmd/help/cmd.go\n\nvar helpCmd = &cobra.Command{\n Use: \"help [topic]\",\n Short: \"Display help documentation\",\n Run: runHelp,\n}\n\nvar searchFlag string\n\nfunc init() {\n helpCmd.Flags().StringVarP(&searchFlag, \"search\", \"s\", \"\", \"Search help topics\")\n}\n\nfunc runHelp(cmd *cobra.Command, args []string) {\n catalog := help.DefaultCatalog()\n \n if searchFlag != \"\" {\n results := catalog.Search(searchFlag)\n // Display search results\n return\n }\n \n if len(args) == 0 {\n // List all topics\n topics := catalog.List()\n for _, t := range topics {\n fmt.Printf(\" %s - %s\\n\", t.ID, t.Title)\n }\n return\n }\n \n // Show specific topic\n topic, err := catalog.Get(args[0])\n if err != nil {\n cli.Error(\"Topic not found: %s\", args[0])\n return\n }\n \n // Render markdown to terminal\n renderTopic(topic)\n}\n```\n\n## Terminal Rendering\n- Use `github.com/charmbracelet/glamour` for markdown\n- Or simple formatting with ANSI colors\n- Pager support for long content (`less` style)\n\n## Acceptance Criteria\n- [ ] `core help` lists topics\n- [ ] `core help ` shows content\n- [ ] `core help --search` finds topics\n- [ ] Markdown rendered nicely in terminal\n- [ ] Pager for long content","number":136,"title":"feat(help): Add CLI help command"},{"body":"## Overview\n\nMerge `pkg/errors` and `pkg/log` into a unified `pkg/log` package with static functions for both logging and error creation. This simplifies the codebase and provides a consistent API.\n\n## Current State\n\n**pkg/log** (2 files import):\n- `Logger` struct with level-based logging\n- Static: `Debug()`, `Info()`, `Warn()`, `Error()`\n- Structured key-value logging\n\n**pkg/errors** (11 files import):\n- `Error` struct with Op, Msg, Err, Code\n- `E()`, `Wrap()`, `WrapCode()`, `Code()`\n- Standard library wrappers: `Is()`, `As()`, `New()`, `Join()`\n\n## Target API\n\n```go\npackage log\n\n// --- Logging (existing) ---\nlog.Debug(\"message\", \"key\", value)\nlog.Info(\"message\", \"key\", value)\nlog.Warn(\"message\", \"key\", value)\nlog.Error(\"message\", \"key\", value)\n\n// --- Error Creation (merged from pkg/errors) ---\nlog.E(\"op\", \"message\", err) // Create structured error\nlog.Wrap(err, \"op\", \"message\") // Wrap with context\nlog.WrapCode(err, \"CODE\", \"op\", \"msg\") // Wrap with error code\n\n// --- Standard library (re-exported) ---\nlog.Is(err, target) // errors.Is\nlog.As(err, &target) // errors.As\nlog.New(\"message\") // errors.New\nlog.Join(errs...) // errors.Join\n\n// --- Error Helpers ---\nlog.Op(err) // Extract operation\nlog.ErrCode(err) // Extract error code\nlog.Message(err) // Extract message\nlog.Root(err) // Get root cause\n\n// --- Combined Helpers (new) ---\nlog.LogError(err, \"op\", \"msg\") // Log + return wrapped error\nlog.Must(err, \"op\", \"msg\") // Panic if error\n```\n\n## Benefits\n\n1. **Single import** - `log` handles both logging and errors\n2. **Consistent patterns** - Same package for observability\n3. **Simpler mental model** - \"If something goes wrong, use log\"\n4. **Natural pairing** - Errors often logged immediately\n\n## Child Issues\n\n### Phase 1: Extend pkg/log (blocking)\n- [ ] #128 - Add error creation functions to pkg/log\n\n### Phase 2: Migration (sequential)\n- [ ] #129 - Create pkg/errors deprecation alias\n- [ ] #130 - Migrate pkg/errors imports to pkg/log (11 files)\n- [ ] #131 - Remove deprecated pkg/errors package\n\n### Phase 3: Enhancements (optional)\n- [ ] #132 - Add combined log-and-return error helpers\n\n## Parallelization Guide\n\n**Can be done by other models (boring/mechanical):**\n- #129 - Deprecation alias (copy-paste with aliases)\n- #130 - Import migration (find/replace)\n- #131 - Cleanup (delete directory)\n\n**Requires more context:**\n- #128 - API design decisions\n- #132 - Helper design\n\n## Migration Path\n\n1. Extend `pkg/log` with error functions (#128)\n2. Create deprecation alias (#129)\n3. Migrate all imports (#130)\n4. Remove `pkg/errors` (#131)\n\n## Acceptance Criteria\n- [ ] Single `pkg/log` import for logging and errors\n- [ ] Zero imports of `pkg/errors`\n- [ ] All tests pass\n- [ ] Combined helpers available (#132)","number":127,"title":"feat(log): Unify pkg/errors and pkg/log into single logging package"},{"body":"Parent: #118\n\n**Complexity: Low** - Similar to socket but simpler\n\n## Task\nAdd TCP transport for network MCP connections.\n\n## Implementation\n\n```go\n// pkg/mcp/transport_tcp.go\n\ntype TCPTransport struct {\n addr string\n listener net.Listener\n}\n\nfunc NewTCPTransport(addr string) (*TCPTransport, error) {\n listener, err := net.Listen(\"tcp\", addr)\n if err != nil {\n return nil, err\n }\n return &TCPTransport{addr: addr, listener: listener}, nil\n}\n```\n\n## Configuration\n- Default: `127.0.0.1:9100` (localhost only)\n- Configurable via `MCP_ADDR` env var\n- Consider TLS for non-localhost\n\n## Security Considerations\n- Default to localhost binding\n- Warn if binding to 0.0.0.0\n- Future: mTLS support\n\n## Acceptance Criteria\n- [ ] TCP listener with configurable address\n- [ ] Localhost-only by default\n- [ ] Multiple concurrent connections\n- [ ] Graceful shutdown","number":126,"title":"feat(mcp): Add TCP transport"},{"body":"Parent: #101\n\n**Complexity: Medium** - 5 files with config/registry operations\n\n## Task\nMigrate `internal/cmd/setup/*` to use `io.Medium`.\n\n## Files\n- Bootstrap commands\n- Registry management\n- GitHub config files","number":116,"title":"chore(io): Migrate internal/cmd/setup to Medium abstraction"},{"body":"Parent: #101\n\n**Complexity: Medium** - 5 files with code generation\n\n## Task\nMigrate `internal/cmd/sdk/*` to use `io.Medium`.\n\n## Files\n- SDK generation commands\n- Generator implementations","number":115,"title":"chore(io): Migrate internal/cmd/sdk to Medium abstraction"},{"body":"Parent: #101\n\n**Complexity: Low** - 3 files\n\n## Task\nMigrate `internal/cmd/dev/*` to use `io.Medium`.\n\n## Files\n- Dev workflow commands\n- Registry operations","number":114,"title":"chore(io): Migrate internal/cmd/dev to Medium abstraction"},{"body":"Parent: #101\n\n**Complexity: Low** - 2 files\n\n## Task\nMigrate `internal/cmd/docs/*` to use `io.Medium`.\n\n## Files\n- Documentation scanning\n- File sync operations","number":113,"title":"chore(io): Migrate internal/cmd/docs to Medium abstraction"},{"body":"Parent: #101\n\n## Task\nReplace custom path validation in `pkg/mcp/mcp.go` with `local.Medium` sandboxing.\n\n## Current State\nThe MCP server has custom `validatePath()` and `resolvePathWithSymlinks()` functions for path security.\n\n## Target State\nUse `local.New(workspaceRoot)` to create a sandboxed Medium, then use Medium methods for all file operations.\n\n## Changes Required\n1. Add `medium local.Medium` field to `Service` struct\n2. Initialize medium in `New()` with workspace root\n3. Replace all file operation handlers to use medium methods\n4. Remove custom `validatePath()` function (Medium handles this)\n5. Update tests\n\n## Benefits\n- Consistent path security across codebase\n- Symlink handling built into Medium\n- Simpler MCP code\n\n## Blocked By\n- #102 (Medium interface extension)","number":103,"title":"feat(io): Migrate pkg/mcp to use Medium abstraction"},{"body":"Follow-up from #87 (NO_COLOR support implemented in #98).\n\n## Remaining Work\n\n### 1. WCAG Color Contrast Audit\nAudit the color combinations in `pkg/cli/styles.go` for WCAG contrast compliance:\n- Check foreground/background contrast ratios\n- Ensure sufficient contrast on both dark and light terminal backgrounds\n- Document any colors that may have accessibility issues\n\n### 2. Terminal Capability Adaptation\nConsider adapting to terminal capabilities:\n- Detect 16/256/TrueColor support\n- Fallback to simpler colors on limited terminals\n- Potentially use a library that handles this automatically\n\n## Reference\n- Current colors: `pkg/cli/styles.go` (Tailwind palette)\n- ANSI implementation: `pkg/cli/ansi.go`\n- WCAG contrast guidelines: https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html\n\n## Relates to\n- #87 (partial implementation)\n- #86 (Accessibility Audit parent)","number":99,"title":"CLI Output: Color contrast audit and terminal adaptation"},{"body":"Review documentation for accessibility best practices.\n\n**Issue:**\n- Automated scans for alt text on images found no direct Markdown/HTML images, but verification is needed for any generated docs.\n- Ensure heading hierarchy is logical (H1 -> H2 -> H3).\n\n**Recommendation:**\n- Add a CI check for markdown accessibility (e.g., markdownlint with a11y rules).\n- Ensure all future diagrams/images have descriptive alt text.","number":89,"title":"Documentation: Improve Accessibility"},{"body":"The Angular application in pkg/updater/ui/src needs a comprehensive accessibility audit.\n\n**Findings:**\n- Missing aria-labels on buttons.\n- Images potentially missing alt text (grep scan found none, but verification needed on dynamic content).\n- No evidence of high-contrast mode support.\n\n**Recommendation:**\n- Run automated a11y tests (e.g., axe-core).\n- Audit keyboard navigation flow.\n- Ensure all interactive elements have accessible names.","number":88,"title":"Web UI: Audit Angular App Accessibility"}] diff --git a/pkg/help/catalog.go b/pkg/help/catalog.go new file mode 100644 index 00000000..04f26687 --- /dev/null +++ b/pkg/help/catalog.go @@ -0,0 +1,87 @@ +package help + +import ( + "fmt" +) + +// Catalog manages help topics. +type Catalog struct { + topics map[string]*Topic + index *searchIndex +} + +// DefaultCatalog returns a catalog with built-in topics. +func DefaultCatalog() *Catalog { + c := &Catalog{ + topics: make(map[string]*Topic), + index: newSearchIndex(), + } + + // Add default topics + c.Add(&Topic{ + ID: "getting-started", + Title: "Getting Started", + Content: `# Getting Started + +Welcome to Core! This CLI tool helps you manage development workflows. + +## Common Commands + +- core dev: Development workflows +- core setup: Setup repository +- core doctor: Check environment health +- core test: Run tests + +## Next Steps + +Run 'core help ' to learn more about a specific topic. +`, + }) + c.Add(&Topic{ + ID: "config", + Title: "Configuration", + Content: `# Configuration + +Core is configured via environment variables and config files. + +## Environment Variables + +- CORE_DEBUG: Enable debug logging +- GITHUB_TOKEN: GitHub API token + +## Config Files + +Config is stored in ~/.core/config.yaml +`, + }) + return c +} + +// Add adds a topic to the catalog. +func (c *Catalog) Add(t *Topic) { + c.topics[t.ID] = t + c.index.Add(t) +} + +// List returns all topics. +func (c *Catalog) List() []*Topic { + var list []*Topic + for _, t := range c.topics { + list = append(list, t) + } + return list +} + +// Search searches for topics. +func (c *Catalog) Search(query string) []*SearchResult { + return c.index.Search(query) +} + +// Get returns a topic by ID. +func (c *Catalog) Get(id string) (*Topic, error) { + t, ok := c.topics[id] + if !ok { + return nil, fmt.Errorf("topic not found: %s", id) + } + return t, nil +}