feat: add project export and import functionality

- Implemented `pcli project export` command to export project hierarchy as JSON.
- Added `pcli project import` command to import project data from JSON.
- Created user client to fetch user details for comment attribution.
- Introduced new data structures for export and import processes.
- Ensured name-based references in exports and handled conflicts during imports.
- Added versioning and progress reporting for import operations.
- Updated documentation and specifications for new features.

cmd/export.go

@@ -0,0 +1,42 @@
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+var projectExportCmd = &cobra.Command{
+	Use:   "export <project-id-or-name>",
+	Short: "Export a project to JSON",
+	Long:  "Export a project (or a specific board) as a portable JSON file to stdout",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		boardFilter, _ := cmd.Flags().GetString("board")
+
+		projectID, err := resolveProject(args[0])
+		if err != nil {
+			return err
+		}
+
+		envelope, err := getClient().ExportProject(getContext(), projectID, boardFilter)
+		if err != nil {
+			return friendlyAPIError(err, "export project", "")
+		}
+
+		encoder := json.NewEncoder(os.Stdout)
+		encoder.SetIndent("", "  ")
+		if err := encoder.Encode(envelope); err != nil {
+			return fmt.Errorf("failed to encode export: %w", err)
+		}
+
+		return nil
+	},
+}
+
+func init() {
+	projectCmd.AddCommand(projectExportCmd)
+	projectExportCmd.Flags().String("board", "", "Filter to a specific board (name or ID)")
+}

cmd/import.go

@@ -0,0 +1,62 @@
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+
+	"git.franklin.lab/steve.cliff/pcli/model"
+	"github.com/spf13/cobra"
+)
+
+var projectImportCmd = &cobra.Command{
+	Use:   "import",
+	Short: "Import a project from JSON",
+	Long:  "Import a project from a JSON export file, creating all resources with new IDs",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		filePath, _ := cmd.Flags().GetString("file")
+
+		var reader io.Reader
+		if filePath != "" {
+			f, err := os.Open(filePath)
+			if err != nil {
+				return fmt.Errorf("failed to open file: %w", err)
+			}
+			defer f.Close()
+			reader = f
+		} else {
+			// Check if stdin has data
+			stat, _ := os.Stdin.Stat()
+			if (stat.Mode() & os.ModeCharDevice) != 0 {
+				return fmt.Errorf("no input provided — use --file or pipe JSON via stdin")
+			}
+			reader = os.Stdin
+		}
+
+		var envelope model.ExportEnvelope
+		if err := json.NewDecoder(reader).Decode(&envelope); err != nil {
+			return fmt.Errorf("failed to parse export JSON: %w", err)
+		}
+
+		if envelope.Version != 1 {
+			return fmt.Errorf("unsupported export version %d (supported: 1)", envelope.Version)
+		}
+
+		progress, err := getClient().ImportProject(getContext(), &envelope, os.Stderr)
+		if err != nil {
+			if progress != nil {
+				fmt.Fprintf(os.Stderr, "Partial import before error: %s\n", progress)
+			}
+			return friendlyAPIError(err, "import project", "")
+		}
+
+		fmt.Fprintf(os.Stderr, "Import complete: %s\n", progress)
+		return nil
+	},
+}
+
+func init() {
+	projectCmd.AddCommand(projectImportCmd)
+	projectImportCmd.Flags().String("file", "", "Path to export JSON file (alternative to stdin)")
+}

cmd/resolve.go

@@ -0,0 +1,43 @@
+package cmd
+
+import (
+	"fmt"
+	"strings"
+)
+
+// resolveProject takes a project ID or name and returns the project ID.
+// If the input matches a project ID exactly, it's returned directly.
+// If it matches project name(s), it returns the ID if exactly one matches.
+func resolveProject(idOrName string) (string, error) {
+	// First try as an ID
+	project, err := getClient().GetProject(getContext(), idOrName)
+	if err == nil {
+		return project.ID, nil
+	}
+
+	// Fall back to name lookup
+	projects, err := getClient().ListProjects(getContext())
+	if err != nil {
+		return "", fmt.Errorf("failed to list projects: %w", err)
+	}
+
+	var matches []struct{ id, name string }
+	for _, p := range projects {
+		if strings.EqualFold(p.Name, idOrName) {
+			matches = append(matches, struct{ id, name string }{p.ID, p.Name})
+		}
+	}
+
+	switch len(matches) {
+	case 0:
+		return "", fmt.Errorf("project %q not found", idOrName)
+	case 1:
+		return matches[0].id, nil
+	default:
+		var names []string
+		for _, m := range matches {
+			names = append(names, fmt.Sprintf("%s (%s)", m.name, m.id))
+		}
+		return "", fmt.Errorf("ambiguous project name %q matches multiple projects: %s", idOrName, strings.Join(names, ", "))
+	}
+}