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/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)")
+}