add modules

Author: atomikpanda

.claude/skills/dotular-module/SKILL.md

@@ -7,6 +7,12 @@ description: Use when user asks to create a dotular module, add a tool to dotula
 
 Create a complete dotular registry module for a tool by researching its config files, scanning the local machine, and writing the module YAML.
 
+## Critical Rule
+
+1. **NEVER use `dotular add`**. That command writes to the user's personal `dotular.yaml` and only sets the destination for the current platform. This skill creates **registry modules** — standalone YAML files in `modules/` with cross-platform destinations. Always create files manually as described in Step 4.
+
+2. **NEVER copy personal config files into registry modules**. Registry modules are shared/generic — they define package items and file destination mappings only. The `file:` items tell dotular *where* a config file belongs, but the actual config content comes from the user's own store, not the registry module. Do NOT create a `modules/<tool>/` subdirectory or copy files like `~/.config/tool/config.toml` into it.
+
 ## Process
 
 ```dot
@@ -56,7 +62,7 @@ ls -la ~/.config/toolname/ 2>/dev/null
 ls -la ~/Library/Application\ Support/ToolName/ 2>/dev/null
 ```
 
-Record which files/directories exist. This validates your research and identifies files available to copy into the module store.
+Record which files/directories exist. This validates your research and confirms the correct destination paths for the `file:` items in the module YAML. Do NOT copy these files — the scan is only to verify paths.
 
 ## Step 3: Present Summary
 
@@ -97,47 +103,34 @@ Include a clear recommendation. Wait for user confirmation before proceeding.
 
 ## Step 4: Execute
 
-After user confirms:
-
-1. **Create module directory** (if config files exist to store):
-   ```bash
-   mkdir -p modules/<tool>/
-   ```
-
-2. **Copy existing config files** into the module store:
-   ```bash
-   cp ~/.config/tool/config.yml modules/<tool>/config.yml
-   ```
-   File placement rule: files go at `modules/<tool>/<filename>` where `<filename>` matches the `file:` value in the YAML. The runner prepends the module name as `sourcePrefix`.
-
-3. **Write module YAML** at `modules/<tool>.yaml`:
-
-   ```yaml
-   name: <tool-name>
-   version: "1.0.0"
-   items:
-     - package: <name>
-       via: brew
-       skip_if: command -v <name>
-       verify: <name> --version
-
-     - package: <name>
-       via: apt
-       skip_if: command -v <name>
-
-     - package: <name-or-id>
-       via: winget
-
-     - file: <filename>
-       destination:
-         macos: <path>
-         linux: <path>
-         windows: <path>
-   ```
+After user confirms, **write the module YAML** at `modules/<tool>.yaml`:
+
+```yaml
+name: <tool-name>
+version: "1.0.0"
+items:
+  - package: <name>
+    via: brew
+    skip_if: command -v <name>
+    verify: <name> --version
+
+  - package: <name>
+    via: apt
+    skip_if: command -v <name>
+
+  - package: <name-or-id>
+    via: winget
+
+  - file: <filename>
+    destination:
+      macos: <path>
+      linux: <path>
+      windows: <path>
+```
 
-   **Multiple package items**: Create a separate `package` item for each platform's package manager (see `dotular.yaml` VS Code module for this pattern). Use `skip_if: command -v <tool>` so only the available manager runs. The runner executes all items — an unavailable package manager simply fails, but `skip_if` prevents redundant installs after the first succeeds.
+**Multiple package items**: Create a separate `package` item for each platform's package manager (see `dotular.yaml` VS Code module for this pattern). Use `skip_if: command -v <tool>` so only the available manager runs. The runner executes all items — an unavailable package manager simply fails, but `skip_if` prevents redundant installs after the first succeeds.
 
-4. If **no config files** to store (package-only module), skip creating the subdirectory.
+**File items**: The `file:` and `directory:` items define destination mappings only — where config files belong on each platform. Do NOT create a `modules/<tool>/` subdirectory or copy personal config files into it. The user's own dotular store provides the actual file content at apply time.
 
 ## Step 5: Verify
 
@@ -172,6 +165,8 @@ Display the complete contents of the generated `modules/<tool>.yaml` for user re
 | Missing `skip_if` on package items | Add `skip_if: command -v <tool>` for idempotency |
 | Using trailing `/` in destination | Match existing convention: `~/.config/tool` not `~/.config/tool/` |
 | Forgetting Windows paths | Always research all 3 platforms for PlatformMap |
+| Using `dotular add` command | NEVER — it writes to personal `dotular.yaml` with single-platform destinations. Manually create `modules/<tool>.yaml` instead |
+| Copying personal config files into module | NEVER — registry modules define destination mappings only, not file content. Do not create `modules/<tool>/` subdirectories or `cp` user configs into them |
 | Editing user's `dotular.yaml` | This skill creates REGISTRY modules only — never touch personal config |
 | Updating `modules/index.yaml` | Out of scope — tell user to add the entry manually |
 

.github/workflows/test.yml

@@ -42,3 +42,19 @@ jobs:
 
       - name: Vet
         run: go vet ./...
+
+      - name: Verify modules index
+        run: |
+          # Generate index.yaml from module files
+          echo "modules:" > /tmp/index.yaml
+          for f in modules/*.yaml; do
+            [ "$(basename "$f")" = "index.yaml" ] && continue
+            name=$(grep '^name:' "$f" | head -1 | sed 's/^name: *//')
+            version=$(grep '^version:' "$f" | head -1 | sed 's/^version: *//')
+            echo "  - name: $name" >> /tmp/index.yaml
+            echo "    version: $version" >> /tmp/index.yaml
+          done
+          if ! diff -u modules/index.yaml /tmp/index.yaml; then
+            echo "::error::modules/index.yaml is out of date. Run 'make index' to regenerate."
+            exit 1
+          fi

Makefile

@@ -1,7 +1,7 @@
 BIN := dotular
 CMD := ./cmd/dotular
 
-.PHONY: build run tidy clean
+.PHONY: build run tidy clean index
 
 build:
 	go build -o ./build/$(BIN) $(CMD)
@@ -24,3 +24,14 @@ test-status:
 
 test-apply-dry:
 	go run $(CMD) apply --dry-run
+
+index:
+	@echo "modules:" > modules/index.yaml
+	@for f in modules/*.yaml; do \
+		[ "$$(basename "$$f")" = "index.yaml" ] && continue; \
+		name=$$(grep '^name:' "$$f" | head -1 | sed 's/^name: *//'); \
+		version=$$(grep '^version:' "$$f" | head -1 | sed 's/^version: *//'); \
+		echo "  - name: $$name" >> modules/index.yaml; \
+		echo "    version: $$version" >> modules/index.yaml; \
+	done
+	@echo "Generated modules/index.yaml"

cmd/dotular/main.go

@@ -702,11 +702,14 @@ func registryCmd() *cobra.Command {
 		Short: "Manage the local registry cache",
 	}
 
-	cmd.AddCommand(
-		&cobra.Command{
-			Use:   "list",
-			Short: "List cached registry modules",
-			RunE: func(cmd *cobra.Command, args []string) error {
+	listCmd := &cobra.Command{
+		Use:   "list",
+		Short: "List available registry modules",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cached, _ := cmd.Flags().GetBool("cached")
+			u := ui.New(os.Stdout, os.Stderr)
+
+			if cached {
 				_, err := loadConfig()
 				if err != nil {
 					return err
@@ -716,7 +719,6 @@ func registryCmd() *cobra.Command {
 				if err != nil {
 					return err
 				}
-				u := ui.New(os.Stdout, os.Stderr)
 				if len(lock.Registry) == 0 {
 					u.Info("(no cached registry modules)")
 					return nil
@@ -726,7 +728,6 @@ func registryCmd() *cobra.Command {
 				for ref, entry := range lock.Registry {
 					ref := registry.ParseRef(ref)
 					trustStr := ref.Trust.String()
-					// Pre-color trust
 					switch trustStr {
 					case "official":
 						trustStr = color.BoldGreen(trustStr)
@@ -743,8 +744,31 @@ func registryCmd() *cobra.Command {
 				}
 				u.Table(headers, rows, nil)
 				return nil
-			},
+			}
+
+			// Default: fetch and display remote index.
+			ctx := context.Background()
+			entries, err := registry.FetchIndex(ctx, u)
+			if err != nil {
+				return err
+			}
+			if len(entries) == 0 {
+				u.Info("(no modules in registry)")
+				return nil
+			}
+			headers := []string{"NAME", "VERSION"}
+			var rows [][]string
+			for _, e := range entries {
+				rows = append(rows, []string{e.Name, e.Version})
+			}
+			u.Table(headers, rows, nil)
+			return nil
 		},
+	}
+	listCmd.Flags().Bool("cached", false, "Show locally cached modules instead of the remote index")
+
+	cmd.AddCommand(
+		listCmd,
 		&cobra.Command{
 			Use:   "clear",
 			Short: "Remove all cached registry modules",

dotular

@@ -1,6 +1,14 @@
 package actions
 
-import "context"
+import (
+	"context"
+	"errors"
+)
+
+// ErrSkipped is returned by an action's Run method when the action cannot
+// proceed but the failure is not an error (e.g. pulling a file that does not
+// exist on the system). The runner treats this as a skip rather than a failure.
+var ErrSkipped = errors.New("skipped")
 
 // Action is a single executable step produced from a config item.
 type Action interface {

internal/actions/action.go

@@ -108,6 +108,9 @@ func (a *DirectoryAction) Run(ctx context.Context, dryRun bool) error {
 
 	switch a.Direction {
 	case "pull":
+		if !dirExists(target) {
+			return fmt.Errorf("pull: system directory does not exist: %s: %w", target, ErrSkipped)
+		}
 		return copyDir(target, a.Source)
 	case "sync":
 		repoExists := dirExists(a.Source)

internal/actions/directory.go

@@ -169,7 +169,7 @@ func (a *FileAction) runPush(destDir, target string) error {
 
 func (a *FileAction) runPull(target string) error {
 	if _, err := os.Stat(target); os.IsNotExist(err) {
-		return fmt.Errorf("pull: system file does not exist: %s", target)
+		return fmt.Errorf("pull: system file does not exist: %s: %w", target, ErrSkipped)
 	}
 	if err := os.MkdirAll(filepath.Dir(a.Source), 0o755); err != nil {
 		return fmt.Errorf("create repo directory: %w", err)

internal/actions/file.go

@@ -48,9 +48,10 @@ func Fetch(ctx context.Context, rawRef string, lock *LockFile, noCache bool, u *
 		return nil, ref.Trust, fmt.Errorf("fetch %s: %w", rawRef, err)
 	}
 
-	// Verify against existing lockfile entry (if any).
+	// Verify against existing lockfile entry when using cache; skip when
+	// explicitly re-fetching so that updated modules are accepted.
 	sum := fmt.Sprintf("%x", sha256.Sum256(data))
-	if inLock && entry.SHA256 != sum {
+	if !noCache && inLock && entry.SHA256 != sum {
 		return nil, ref.Trust, fmt.Errorf(
 			"registry: checksum mismatch for %s after re-fetch (lockfile: %s, got: %s)",
 			rawRef, entry.SHA256, sum,

internal/registry/fetch.go

@@ -4,6 +4,7 @@ package runner
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -340,6 +341,14 @@ func (r *Runner) applyItem(ctx context.Context, mod config.Module, item config.I
 
 	start := time.Now()
 	runErr := action.Run(ctx, false)
+
+	if runErr != nil && errors.Is(runErr, actions.ErrSkipped) {
+		msg := strings.TrimSuffix(runErr.Error(), ": "+actions.ErrSkipped.Error())
+		r.UI.Skip(msg, action.Describe())
+		audit.Log(audit.Entry{Command: r.Command, Module: mod.Name, Item: action.Describe(), Outcome: "skipped"})
+		return outcomeSkipped, nil
+	}
+
 	r.UI.ItemResult(action.Describe(), time.Since(start), runErr)
 
 	outcome, errMsg := "success", ""