diff --git a/docs/n8n_package_import.md b/docs/n8n_package_import.md index 9b3256c..2fce09c 100644 --- a/docs/n8n_package_import.md +++ b/docs/n8n_package_import.md @@ -18,13 +18,16 @@ state (archiving needs workflow:delete), folder overwrite can remove workflows the package does not contain (archive is recoverable, hard-delete also drops executions permanently, so prefer archive), missing credentials become empty stubs unless --credential-missing-mode -is must-preexist or create-with-values, --data-table-schema-policy +is must-preexist or create-with-values, --credential-conflict-policy +overwrite writes the package's credential name and expression values +to matched credentials, --data-table-schema-policy overwrite permanently drops the values in removed or retyped columns, and folders, tags, variables, or tables may be created or overwritten. Interactive runs ask for confirmation and non-interactive runs require --yes; --file - also requires --yes because stdin cannot answer. Credentials created from incomplete package data are reported on -stderr and keep their workflows unpublished until completed. Needs +stderr and keep their workflows unpublished until completed. When the +import is blocked (409 or 422), each issue is listed on stderr. Needs workflow:import plus, depending on the package and the policies, credential, variable, tag, data-table, folder, and delete scopes, and the Packages, Variables, and Folders features where the contents @@ -52,6 +55,7 @@ n8n package import [flags] ``` --bindings string explicit credential bindings as JSON, e.g. '{"credentials":{"pkg-id":"target-id"}}' (default: server default {}) --context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list') + --credential-conflict-policy string matched credential whose package values differ: keep-existing never changes it, overwrite writes the package name and expression values to credentials a project of the import owns (keeps secrets, other fields, and OAuth connections; reported in credentials.updated), fail rejects the import with a 409 credential-conflict; overwrite and fail need credential:update on matched credentials (default: server default keep-existing) --credential-matching-mode string how package credential references match: id-only, name-and-type, or type-only (default: server default id-only) --credential-missing-mode string unresolvable credential handling: must-preexist rejects, create-stub creates empty placeholders, create-with-values seeds them from the package's expression values (needs credential:create; unconfirmed data lands in credentials.incomplete and blocks publishing) (default: server default create-stub) --data-table-matching-mode string data-table matching: by-id, the only mode (default: server default by-id) diff --git a/internal/cli/n8n_package.go b/internal/cli/n8n_package.go index 6fe613b..de2dca8 100644 --- a/internal/cli/n8n_package.go +++ b/internal/cli/n8n_package.go @@ -365,6 +365,7 @@ type packageImportFlags struct { folderID string credentialMatching string credentialMissing string + credentialConflict string bindings string workflowConflict string workflowIDPolicy string @@ -404,13 +405,16 @@ func newPackageImportCommand(opts Options) *cobra.Command { "workflows the package does not contain (archive is recoverable,\n" + "hard-delete also drops executions permanently, so prefer archive),\n" + "missing credentials become empty stubs unless --credential-missing-mode\n" + - "is must-preexist or create-with-values, --data-table-schema-policy\n" + + "is must-preexist or create-with-values, --credential-conflict-policy\n" + + "overwrite writes the package's credential name and expression values\n" + + "to matched credentials, --data-table-schema-policy\n" + "overwrite permanently drops the values in removed or retyped columns,\n" + "and folders, tags, variables, or tables may be created or overwritten.\n" + "Interactive runs ask for confirmation and non-interactive runs require\n" + "--yes; --file - also requires --yes because stdin cannot answer.\n" + "Credentials created from incomplete package data are reported on\n" + - "stderr and keep their workflows unpublished until completed. Needs\n" + + "stderr and keep their workflows unpublished until completed. When the\n" + + "import is blocked (409 or 422), each issue is listed on stderr. Needs\n" + "workflow:import plus, depending on the package and the policies,\n" + "credential, variable, tag, data-table, folder, and delete scopes, and\n" + "the Packages, Variables, and Folders features where the contents\n" + @@ -431,6 +435,7 @@ func newPackageImportCommand(opts Options) *cobra.Command { cmd.Flags().StringVar(&f.folderID, "folder-id", "", "folder within the target project, from 'n8n folder list PROJECT_ID' (default: the project root)") cmd.Flags().StringVar(&f.credentialMatching, "credential-matching-mode", "", "how package credential references match: id-only, name-and-type, or type-only (default: server default id-only)") cmd.Flags().StringVar(&f.credentialMissing, "credential-missing-mode", "", "unresolvable credential handling: must-preexist rejects, create-stub creates empty placeholders, create-with-values seeds them from the package's expression values (needs credential:create; unconfirmed data lands in credentials.incomplete and blocks publishing) (default: server default create-stub)") + cmd.Flags().StringVar(&f.credentialConflict, "credential-conflict-policy", "", "matched credential whose package values differ: keep-existing never changes it, overwrite writes the package name and expression values to credentials a project of the import owns (keeps secrets, other fields, and OAuth connections; reported in credentials.updated), fail rejects the import with a 409 credential-conflict; overwrite and fail need credential:update on matched credentials (default: server default keep-existing)") cmd.Flags().StringVar(&f.bindings, "bindings", "", "explicit credential bindings as JSON, e.g. '{\"credentials\":{\"pkg-id\":\"target-id\"}}' (default: server default {})") cmd.Flags().StringVar(&f.workflowConflict, "workflow-conflict-policy", "", "matching workflow handling, required: new-version, fail, or skip") cmd.Flags().StringVar(&f.workflowIDPolicy, "workflow-id-policy", n8n.ImportWorkflowIDSource, "ID for newly created workflows, always sent: source reuses the package ID for promotions, new mints a fresh ID for repeat imports (default: source)") @@ -468,6 +473,7 @@ func runPackageImport(ctx context.Context, opts Options, f packageImportFlags) e FolderID: strings.TrimSpace(f.folderID), CredentialMatchingMode: strings.TrimSpace(f.credentialMatching), CredentialMissingMode: strings.TrimSpace(f.credentialMissing), + CredentialConflict: strings.TrimSpace(f.credentialConflict), Bindings: strings.TrimSpace(f.bindings), WorkflowConflictPolicy: strings.TrimSpace(f.workflowConflict), WorkflowIDPolicy: strings.TrimSpace(f.workflowIDPolicy), @@ -508,6 +514,7 @@ func runPackageImport(ctx context.Context, opts Options, f packageImportFlags) e if refused := f.idempotency.refusal(err, resolution); refused != nil { return refused } + writeImportIssues(opts.Streams.Err, err) return packageAPIError(err, resolution, "import", allOf("workflow:import")) } if f.output == outputJSON { @@ -559,6 +566,9 @@ func packageImportQuestion(f packageImportFlags, resolution config.Resolution) s default: question += " " + credentials + ", and folders, tags, variables, or tables may be created or overwritten." } + if strings.TrimSpace(f.credentialConflict) == n8n.ImportCredentialConflictOverwrite { + question += " Credential overwrite writes the package's names and expression values to matched credentials that differ." + } if strings.TrimSpace(f.dataTableSchema) == n8n.ImportDataTableSchemaOverwrite { question += " Data-table schema overwrite reshapes matched tables to the package and permanently deletes the values in removed or retyped columns, for every workflow using those tables." } @@ -602,8 +612,8 @@ func writePackageImportText(opts Options, resolution config.Resolution, result * fmt.Fprintf(tw, "Imported:\t%d workflows (%d created, %d updated, %d skipped)\n", len(result.Workflows), created, updated, skipped) fmt.Fprintf(tw, "Removed:\t%d workflows, %d folders\n", len(result.RemovedWorkflows), len(result.RemovedFolders)) fmt.Fprintf(tw, "Shells:\t%d folders, %d projects\n", len(result.Folders), len(result.Projects)) - fmt.Fprintf(tw, "Credentials:\t%d matched, %d stubbed, %d seeded, %d incomplete\n", - len(result.Credentials.Matched), len(result.Credentials.Stubbed), len(result.Credentials.Seeded), len(result.Credentials.Incomplete)) + fmt.Fprintf(tw, "Credentials:\t%d matched, %d updated, %d stubbed, %d seeded, %d incomplete\n", + len(result.Credentials.Matched), len(result.Credentials.Updated), len(result.Credentials.Stubbed), len(result.Credentials.Seeded), len(result.Credentials.Incomplete)) fmt.Fprintf(tw, "Data tables:\t%d matched, %d created, %d updated\n", result.DataTables.Matched, result.DataTables.Created, result.DataTables.Updated) fmt.Fprintf(tw, "Variables:\t%d matched, %d created, %d stubbed, %d updated, %d missing\n", len(result.Variables.Matched), len(result.Variables.Created), len(result.Variables.Stubbed), len(result.Variables.Updated), len(result.Variables.Missing)) @@ -623,7 +633,11 @@ func writePackageImportText(opts Options, resolution config.Resolution, result * } if len(result.Credentials.Incomplete) > 0 { fmt.Fprintf(opts.Streams.Err, "%d credential(s) created from package data that may be incomplete (%s): workflows using them stay unpublished until you complete each with 'n8n credential update '; see credentials.incomplete in --output json.\n", - len(result.Credentials.Incomplete), strings.Join(importedCredentialIDs(result), ", ")) + len(result.Credentials.Incomplete), strings.Join(targetCredentialIDs(result, result.Credentials.Incomplete), ", ")) + } + if len(result.Credentials.Updated) > 0 { + fmt.Fprintf(opts.Streams.Err, "%d matched credential(s) overwritten with package values (%s): see credentials.updated in --output json.\n", + len(result.Credentials.Updated), strings.Join(targetCredentialIDs(result, result.Credentials.Updated), ", ")) } if len(result.Variables.Missing) > 0 { fmt.Fprintf(opts.Streams.Err, "%d variable(s) still unresolved: workflows referencing them may fail until the variables exist.\n", len(result.Variables.Missing)) @@ -643,11 +657,11 @@ func writePackageImportText(opts Options, resolution config.Resolution, result * return nil } -// importedCredentialIDs maps the incomplete source credential IDs to their IDs -// on this instance, keeping the source ID when no binding names one. -func importedCredentialIDs(result *n8n.ImportPackageResult) []string { - ids := make([]string, 0, len(result.Credentials.Incomplete)) - for _, source := range result.Credentials.Incomplete { +// targetCredentialIDs maps source credential IDs to their IDs on this +// instance, keeping the source ID when no binding names one. +func targetCredentialIDs(result *n8n.ImportPackageResult, sources []string) []string { + ids := make([]string, 0, len(sources)) + for _, source := range sources { if target := result.Bindings.Credentials[source]; target != "" { ids = append(ids, target) continue @@ -657,6 +671,19 @@ func importedCredentialIDs(result *n8n.ImportPackageResult) []string { return ids } +// writeImportIssues lists each issue of a blocked import on w, one line per +// issue; other errors write nothing. +func writeImportIssues(w io.Writer, err error) { + blocked, ok := n8n.AsImportBlocked(err) + if !ok || len(blocked.Issues) == 0 { + return + } + fmt.Fprintf(w, "Blocking issues (%d):\n", len(blocked.Issues)) + for _, issue := range blocked.Issues { + fmt.Fprintf(w, " - %s\n", issue.Describe()) + } +} + type packageImportSelectionFlags struct { instance instanceFlags file string @@ -773,6 +800,7 @@ func runPackageImportSelection(ctx context.Context, opts Options, f packageImpor if refused := f.idempotency.refusal(err, resolution); refused != nil { return refused } + writeImportIssues(opts.Streams.Err, err) need := allOf("workflow:import") if len(request.DeletedWorkflowIDs) > 0 { need = allOf("workflow:import", "workflow:delete") @@ -832,9 +860,9 @@ func packageAPIError(err error, resolution config.Resolution, action string, nee } if blocked, ok := n8n.AsImportBlocked(err); ok && action == "import" { if blocked.StatusCode == http.StatusConflict { - return fmt.Errorf("%s rejected the package import (409): %d conflict issue(s); nothing matched with fail stays unchanged, so adjust a conflict policy such as --workflow-conflict-policy, --project-conflict-policy, --folder-conflict-policy, --tag-conflict-policy, or --variable-conflict-policy and retry: %w", resolution.URL, len(blocked.Issues), err) + return fmt.Errorf("%s rejected the package import (409): %d conflict issue(s); nothing matched with fail stays unchanged, so adjust a conflict policy such as --workflow-conflict-policy, --project-conflict-policy, --folder-conflict-policy, --tag-conflict-policy, --variable-conflict-policy, or --credential-conflict-policy and retry: %w", resolution.URL, len(blocked.Issues), err) } - return fmt.Errorf("%s rejected the package import (422): %d blocking issue(s) such as unresolved credentials or variables, unknown node types, or variable quota; create the missing references, pass --credential-missing-mode, --missing-node-type-mode import-anyway, or a variable mode that creates them, and retry: %w", resolution.URL, len(blocked.Issues), err) + return fmt.Errorf("%s rejected the package import (422): %d blocking issue(s) such as unresolved credentials or variables, unknown node types, or variable quota; create the missing references, pass --credential-missing-mode, --missing-node-type-mode import-anyway, or a variable mode that creates them (credential-update-forbidden needs credential:update on the matched credential, or --credential-conflict-policy keep-existing), and retry: %w", resolution.URL, len(blocked.Issues), err) } switch { case n8n.IsStatus(err, http.StatusBadRequest): @@ -855,7 +883,7 @@ func packageAPIError(err error, resolution config.Resolution, action string, nee "workflow:delete is also needed when an update changes a workflow's archive state, and the instance needs the licensed Packages feature.", packageResource) } return forbiddenScopeError(err, resolution, "package import", need, - "the import also needs the credential (create-with-values), variable, tag, data-table (dataTable:update for schema overwrite), folder and delete scopes the package and policies require, and the instance needs the licensed Packages feature.", packageResource) + "the import also needs the credential (credential:create for create-with-values, credential:update for --credential-conflict-policy overwrite or fail), variable, tag, data-table (dataTable:update for schema overwrite), folder and delete scopes the package and policies require, and the instance needs the licensed Packages feature.", packageResource) case n8n.IsNotFound(err): return fmt.Errorf("%s does not serve n8n packages (404): it needs the licensed Packages feature; run %s to see what this instance offers: %w", resolution.URL, discoverHint(packageResource), err) diff --git a/internal/cli/n8n_package_test.go b/internal/cli/n8n_package_test.go index 74beddd..1f83f2c 100644 --- a/internal/cli/n8n_package_test.go +++ b/internal/cli/n8n_package_test.go @@ -421,7 +421,7 @@ func TestPackageImportReportsIncompleteCredentials(t *testing.T) { if fields["credentialMissingMode"] != "create-with-values" || fields["dataTableSchemaConflictPolicy"] != "overwrite-non-destructive" { t.Errorf("fields = %v, want the new modes sent", fields) } - for _, want := range []string{"1 matched, 0 stubbed, 1 seeded, 1 incomplete", "1 matched, 0 created, 2 updated"} { + for _, want := range []string{"1 matched, 0 updated, 0 stubbed, 1 seeded, 1 incomplete", "1 matched, 0 created, 2 updated"} { if !strings.Contains(got.stdout, want) { t.Errorf("stdout missing %q:\n%s", want, got.stdout) } @@ -799,3 +799,162 @@ func TestPackageImportSelectionErrorsPointAtFix(t *testing.T) { t.Errorf("404 result = %+v, want the availability hint", got) } } + +const cliPackageImportResultUpdated = `{ + "package":{"sourceN8nVersion":"2.46.4","sourceId":"pkg-3","exportedAt":"2026-11-01T00:00:00.000Z"}, + "workflows":[],"removedWorkflows":[],"removedFolders":[],"folders":[],"projects":[], + "bindings":{"workflows":{},"credentials":{"c-up":"t-up"}}, + "credentials":{"matched":["c-ok"],"stubbed":[],"seeded":[],"incomplete":[],"updated":["c-up"]}, + "dataTables":{"matched":0,"created":0,"updated":0}, + "variables":{"matched":[],"missing":[],"created":[],"stubbed":[],"updated":[]}, + "tags":{"matched":[],"created":[],"renamed":[],"reconciled":[],"skipped":[]} +}` + +func TestPackageImportCredentialConflictPolicy(t *testing.T) { + f := packageFixture(t, cliPackageImportResultUpdated) + archive := writePackageArchive(t, cliPackageArchive) + before := f.requestCount() + + got := f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--credential-conflict-policy", "replace", "--yes") + if got.code != ExitError || f.requestCount() != before { + t.Fatalf("bad policy result = %+v, requests = %d want %d", got, f.requestCount(), before) + } + for _, want := range []string{`unknown credential-conflict policy "replace"`, "keep-existing, overwrite, fail"} { + if !strings.Contains(got.stderr, want) { + t.Errorf("stderr = %q, want %q", got.stderr, want) + } + } + + f.stdin = "no\n" + got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--credential-conflict-policy", "overwrite") + if got.code != ExitError || f.requestCount() != before || !strings.Contains(got.stderr, "Credential overwrite writes the package's names and expression values") { + t.Errorf("declined overwrite result = %+v, want the overwrite warning in the prompt and no request", got) + } + + got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--credential-conflict-policy", "overwrite", "--yes") + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + fields, _, _ := parseCLIImportMultipart(t, f) + if fields["credentialConflictPolicy"] != "overwrite" { + t.Errorf("fields = %v, want credentialConflictPolicy overwrite", fields) + } + if !strings.Contains(got.stdout, "1 matched, 1 updated, 0 stubbed, 0 seeded, 0 incomplete") { + t.Errorf("stdout missing the updated count:\n%s", got.stdout) + } + for _, want := range []string{"1 matched credential(s) overwritten", "t-up", "credentials.updated"} { + if !strings.Contains(got.stderr, want) { + t.Errorf("stderr missing %q:\n%s", want, got.stderr) + } + } + if strings.Contains(got.stdout, "overwritten") { + t.Errorf("stdout = %q, want the overwrite note on stderr only", got.stdout) + } + + got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes") + if got.code != ExitSuccess { + t.Fatalf("unset exit = %d, stderr: %s", got.code, got.stderr) + } + fields, _, _ = parseCLIImportMultipart(t, f) + if _, sent := fields["credentialConflictPolicy"]; sent { + t.Errorf("fields = %v, want credentialConflictPolicy omitted when the flag is unset", fields) + } + + got = f.run("package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes", "--output", "json") + if got.code != ExitSuccess { + t.Fatalf("json exit = %d, stderr: %s", got.code, got.stderr) + } + var decoded struct { + Credentials struct { + Updated []string `json:"updated"` + } `json:"credentials"` + } + if err := json.Unmarshal([]byte(got.stdout), &decoded); err != nil || len(decoded.Credentials.Updated) != 1 || decoded.Credentials.Updated[0] != "c-up" { + t.Errorf("json = %s (error %v), want credentials.updated kept", got.stdout, err) + } +} + +func TestPackageImportToleratesAbsentCredentialsUpdated(t *testing.T) { + f := packageFixture(t, cliPackageImportResult) + archive := writePackageArchive(t, cliPackageArchive) + + for _, args := range [][]string{ + {"package", "import", "--file", archive, "--workflow-conflict-policy", "skip", "--yes"}, + {"package", "import-selection", "--file", archive, "--project-id", "p1", "--workflow-id", "wf-src", "--yes"}, + } { + got := f.run(args...) + if got.code != ExitSuccess { + t.Fatalf("%v exit = %d, stderr: %s", args, got.code, got.stderr) + } + if !strings.Contains(got.stdout, "0 matched, 0 updated, 1 stubbed") || strings.Contains(got.stderr, "overwritten") { + t.Errorf("%v output:\n--- stdout ---\n%s\n--- stderr ---\n%s\nwant 0 updated and no overwrite note", args, got.stdout, got.stderr) + } + } +} + +func TestPackageImportSelectionReportsCredentialsUpdated(t *testing.T) { + f := packageFixture(t, cliPackageImportResultUpdated) + archive := writePackageArchive(t, cliPackageArchive) + + got := f.run("package", "import-selection", "--file", archive, "--project-id", "p1", "--workflow-id", "wf-src", "--yes") + if got.code != ExitSuccess { + t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr) + } + if !strings.Contains(got.stdout, "1 updated") || !strings.Contains(got.stderr, "t-up") { + t.Errorf("output:\n--- stdout ---\n%s\n--- stderr ---\n%s\nwant the updated credential", got.stdout, got.stderr) + } +} + +const cliPackageBlockedNewIssues = `{"message":"import blocked","issues":[ +{"type":"agent-conflict","kind":"existing","sourceAgentId":"ag-1","projectId":"p1","targetIds":["ag-x"]}, +{"type":"agent-invalid","sourceAgentId":"ag-2","path":"agents/ag-2.json","message":"missing model"}, +{"type":"agent-dependency-unresolved","sourceAgentId":"ag-3","projectId":"p1","dependencyType":"credential","referenceId":"c-9","path":"tools[1]","reason":"missing"}, +{"type":"agent-policy-violation","sourceAgentId":"ag-4","name":"Helper","violations":[{"kind":"block","checkId":"no-shell","message":"shell tool not allowed"}]}, +{"type":"workflow-folder-conflict","sourceWorkflowId":"wf-1","existingWorkflowId":"wf-9","existingParentFolderId":"f-old","targetFolderId":null,"name":"Flow"}, +{"type":"credential-policy-violation","sourceId":"c-1","targetId":"t-1","name":"Slack","credentialType":"slackApi","usedBy":[],"violations":[{"kind":"deny","checkId":"no-update","message":"updates refused"}]}, +{"type":"future-thing","detail":"kept"}]}` + +func TestPackageImportBlockedListsIssues(t *testing.T) { + archive := writePackageArchive(t, cliPackageArchive) + wantLines := []string{ + "Blocking issues (7):", + ` - agent-conflict (existing): agent "ag-1" in project "p1" matches existing agent(s) ag-x`, + ` - agent-invalid: agent "ag-2" at agents/ag-2.json: missing model`, + ` - agent-dependency-unresolved: agent "ag-3" in project "p1": credential "c-9" at tools[1] is missing`, + ` - agent-policy-violation: agent "Helper" (ag-4) refused: no-shell: shell tool not allowed`, + ` - workflow-folder-conflict: workflow "Flow" (wf-1) matches existing workflow "wf-9" in folder "f-old", but the import targets the project root`, + ` - credential-policy-violation: credential "Slack" (c-1, type slackApi, update of target "t-1") refused: no-update: updates refused`, + ` - future-thing: detail="kept"`, + } + for _, tc := range []struct { + name string + status int + args []string + want string + }{ + {"import 409", http.StatusConflict, []string{"package", "import", "--file", archive, "--workflow-conflict-policy", "fail", "--yes"}, "--credential-conflict-policy"}, + {"import 422", http.StatusUnprocessableEntity, []string{"package", "import", "--file", archive, "--workflow-conflict-policy", "fail", "--yes"}, "credential:update"}, + {"selection 409", http.StatusConflict, []string{"package", "import-selection", "--file", archive, "--project-id", "p1", "--workflow-id", "wf-1", "--yes"}, "409"}, + {"selection 422", http.StatusUnprocessableEntity, []string{"package", "import-selection", "--file", archive, "--project-id", "p1", "--workflow-id", "wf-1", "--yes"}, "422"}, + } { + t.Run(tc.name, func(t *testing.T) { + f := packageFixture(t, "") + f.route = func(*http.Request, int) (int, string) { return tc.status, cliPackageBlockedNewIssues } + got := f.run(tc.args...) + if got.code != ExitError { + t.Fatalf("exit = %d, want %d (stderr: %s)", got.code, ExitError, got.stderr) + } + if got.stdout != "" { + t.Errorf("stdout = %q, want empty: issues are diagnostics", got.stdout) + } + for _, want := range append(wantLines, tc.want) { + if !strings.Contains(got.stderr, want) { + t.Errorf("stderr missing %q:\n%s", want, got.stderr) + } + } + if strings.Contains(got.stderr, "null") { + t.Errorf("stderr = %q, want a null target folder rendered as the project root", got.stderr) + } + }) + } +} diff --git a/internal/n8n/n8n_package.go b/internal/n8n/n8n_package.go index d20830c..15a1a75 100644 --- a/internal/n8n/n8n_package.go +++ b/internal/n8n/n8n_package.go @@ -19,6 +19,7 @@ import ( "mime/multipart" "net/http" "slices" + "strconv" "strings" "time" ) @@ -300,6 +301,10 @@ const ( ImportCredentialMissingCreateStub = "create-stub" ImportCredentialMissingCreateWithValues = "create-with-values" + ImportCredentialConflictKeep = "keep-existing" + ImportCredentialConflictOverwrite = "overwrite" + ImportCredentialConflictFail = "fail" + ImportWorkflowConflictNewVersion = "new-version" ImportWorkflowConflictFail = "fail" ImportWorkflowConflictSkip = "skip" @@ -360,6 +365,7 @@ const ( var ( importCredentialMatchModes = []string{ImportCredentialMatchIDOnly, ImportCredentialMatchNameAndType, ImportCredentialMatchTypeOnly} importCredentialMissingModes = []string{ImportCredentialMissingMustPreexist, ImportCredentialMissingCreateStub, ImportCredentialMissingCreateWithValues} + importCredentialConflicts = []string{ImportCredentialConflictKeep, ImportCredentialConflictOverwrite, ImportCredentialConflictFail} importWorkflowConflicts = []string{ImportWorkflowConflictNewVersion, ImportWorkflowConflictFail, ImportWorkflowConflictSkip} importWorkflowIDPolicies = []string{ImportWorkflowIDNew, ImportWorkflowIDSource} importMissingNodeModes = []string{ImportMissingNodeFail, ImportMissingNodeImportAnyway} @@ -387,6 +393,7 @@ type ImportPackageRequest struct { FolderID string `json:"-"` CredentialMatchingMode string `json:"-"` CredentialMissingMode string `json:"-"` + CredentialConflict string `json:"-"` // credentialConflictPolicy; overwrite and fail need credential:update Bindings string `json:"-"` WorkflowConflictPolicy string `json:"-"` WorkflowIDPolicy string `json:"-"` @@ -427,6 +434,7 @@ func (r ImportPackageRequest) Validate() error { }{ {r.CredentialMatchingMode, importCredentialMatchModes, "credential-matching mode"}, {r.CredentialMissingMode, importCredentialMissingModes, "credential-missing mode"}, + {r.CredentialConflict, importCredentialConflicts, "credential-conflict policy"}, {r.MissingNodeTypeMode, importMissingNodeModes, "missing-node-type mode"}, {r.WorkflowPublishingPolicy, importPublishPolicies, "workflow-publishing policy"}, {r.ProjectConflictPolicy, importProjectConflicts, "project-conflict policy"}, @@ -472,6 +480,7 @@ func (r ImportPackageRequest) fields() map[string]string { set("folderId", r.FolderID) set("credentialMatchingMode", r.CredentialMatchingMode) set("credentialMissingMode", r.CredentialMissingMode) + set("credentialConflictPolicy", r.CredentialConflict) set("bindings", r.Bindings) set("missingNodeTypeMode", r.MissingNodeTypeMode) set("workflowPublishingPolicy", r.WorkflowPublishingPolicy) @@ -726,15 +735,18 @@ type ImportBindings struct { // ImportCredentials groups source credential IDs by outcome: matched an // existing credential, created as an empty stub, created with all source data -// (seeded), or created from bundled values the package does not confirm are -// complete. Incomplete credentials need input and block publishing of the -// workflows that use them (incomplete-credential). Target IDs are in -// [ImportBindings.Credentials]. +// (seeded), created from bundled values the package does not confirm are +// complete, or matched a credential the import changed under +// credentialConflictPolicy overwrite (updated, not also listed as matched). +// Incomplete credentials need input and block publishing of the workflows that +// use them (incomplete-credential). Updated is absent before n8n 2.46 and +// decodes as nil. Target IDs are in [ImportBindings.Credentials]. type ImportCredentials struct { Matched []string `json:"matched"` Stubbed []string `json:"stubbed"` Seeded []string `json:"seeded"` Incomplete []string `json:"incomplete"` + Updated []string `json:"updated"` } // ImportDataTables counts matched, created, and schema-updated data tables. @@ -762,23 +774,79 @@ type ImportTags struct { Skipped []string `json:"skipped"` } -// ImportBlockingIssue is one reason a 409 or 422 rejected an import. Only the -// discriminator is interpreted; the full document is preserved verbatim so new -// issue kinds survive without a client change. +// Import blocking issue types the client renders in detail. Every other type, +// including ones a newer server adds, renders generically from Raw. +const ( + ImportIssueAgentConflict = "agent-conflict" + ImportIssueAgentInvalid = "agent-invalid" + ImportIssueAgentDependencyUnresolved = "agent-dependency-unresolved" + ImportIssueAgentPolicyViolation = "agent-policy-violation" + ImportIssueWorkflowFolderConflict = "workflow-folder-conflict" + ImportIssueCredentialPolicyViolation = "credential-policy-violation" +) + +// ImportBlockingIssue is one reason a 409 or 422 rejected an import. The +// discriminator and the fields of the variants rendered in detail are decoded; +// a field a variant does not carry stays zero. The full document is preserved +// verbatim in Raw so new issue kinds survive without a client change. +// +// TargetFolderID and ExistingParentFolderID are nil for the project root +// (workflow-folder-conflict). TargetID on credential-policy-violation is set +// only when the policy refused an update of a matched credential. type ImportBlockingIssue struct { - Type string `json:"type"` - Raw json.RawMessage `json:"-"` + Type string `json:"type"` + Kind string `json:"kind,omitempty"` + Name string `json:"name,omitempty"` + Message string `json:"message,omitempty"` + Path string `json:"path,omitempty"` + ProjectID string `json:"projectId,omitempty"` + SourceAgentID string `json:"sourceAgentId,omitempty"` + SourceTaskID string `json:"sourceTaskId,omitempty"` + TargetIDs []string `json:"targetIds,omitempty"` + DependencyType string `json:"dependencyType,omitempty"` + ReferenceID string `json:"referenceId,omitempty"` + Reason string `json:"reason,omitempty"` + SourceWorkflowID string `json:"sourceWorkflowId,omitempty"` + ExistingWorkflowID string `json:"existingWorkflowId,omitempty"` + ExistingParentFolderID *string `json:"existingParentFolderId,omitempty"` + TargetFolderID *string `json:"targetFolderId,omitempty"` + SourceID string `json:"sourceId,omitempty"` + TargetID string `json:"targetId,omitempty"` + CredentialType string `json:"credentialType,omitempty"` + Violations []ImportIssueViolation `json:"violations,omitempty"` + Raw json.RawMessage `json:"-"` +} + +// ImportIssueViolation is one policy check that refused an agent, workflow, or +// credential in a *-policy-violation issue. +type ImportIssueViolation struct { + Kind string `json:"kind"` + CheckID string `json:"checkId"` + Message string `json:"message"` + Subject string `json:"subject,omitempty"` + SubjectType string `json:"subjectType,omitempty"` + Scope string `json:"scope,omitempty"` + MatchedRuleID string `json:"matchedRuleId,omitempty"` + ProjectID string `json:"projectId,omitempty"` + OptInAvailable bool `json:"optInAvailable,omitempty"` } -// UnmarshalJSON keeps the discriminator and the verbatim document. +// UnmarshalJSON decodes the named fields and keeps the verbatim document. A +// field whose shape differs from the named one (a variant this client does not +// know reusing a name) is left zero rather than failing the whole error. func (issue *ImportBlockingIssue) UnmarshalJSON(data []byte) error { - var typed struct { - Type string `json:"type"` - } - if err := json.Unmarshal(data, &typed); err != nil { - return err + type plain ImportBlockingIssue + var decoded plain + if err := json.Unmarshal(data, &decoded); err != nil { + var typed struct { + Type string `json:"type"` + } + if err := json.Unmarshal(data, &typed); err != nil { + return err + } + decoded = plain{Type: typed.Type} } - issue.Type = typed.Type + *issue = ImportBlockingIssue(decoded) issue.Raw = append([]byte(nil), data...) return nil } @@ -788,9 +856,139 @@ func (issue ImportBlockingIssue) MarshalJSON() ([]byte, error) { if len(issue.Raw) > 0 { return issue.Raw, nil } - return json.Marshal(struct { - Type string `json:"type"` - }{Type: issue.Type}) + type plain ImportBlockingIssue + return json.Marshal(plain(issue)) +} + +// Describe renders the issue as one human-readable line starting with its +// type. Agent issues, workflow-folder-conflict, and +// credential-policy-violation get a sentence; every other type lists its +// scalar fields from Raw as key=value pairs, so unknown types still read. +func (issue ImportBlockingIssue) Describe() string { + typ := emptyImportIssueType(issue.Type) + switch issue.Type { + case ImportIssueAgentConflict: + line := fmt.Sprintf("%s (%s): agent %s", typ, dashIfEmpty(issue.Kind), quoteOrDash(issue.SourceAgentID)) + if issue.SourceTaskID != "" { + line += fmt.Sprintf(" task %q", issue.SourceTaskID) + } + return line + fmt.Sprintf(" in project %s matches existing agent(s) %s", + quoteOrDash(issue.ProjectID), joinOrDash(issue.TargetIDs)) + case ImportIssueAgentInvalid: + return fmt.Sprintf("%s: agent %s at %s: %s", typ, quoteOrDash(issue.SourceAgentID), dashIfEmpty(issue.Path), dashIfEmpty(issue.Message)) + case ImportIssueAgentDependencyUnresolved: + return fmt.Sprintf("%s: agent %s in project %s: %s %s at %s is %s", typ, + quoteOrDash(issue.SourceAgentID), quoteOrDash(issue.ProjectID), dashIfEmpty(issue.DependencyType), + quoteOrDash(issue.ReferenceID), dashIfEmpty(issue.Path), dashIfEmpty(issue.Reason)) + case ImportIssueAgentPolicyViolation: + return fmt.Sprintf("%s: agent %s (%s) refused: %s", typ, quoteOrDash(issue.Name), dashIfEmpty(issue.SourceAgentID), describeViolations(issue.Violations)) + case ImportIssueWorkflowFolderConflict: + return fmt.Sprintf("%s: workflow %s (%s) matches existing workflow %s in %s, but the import targets %s", typ, + quoteOrDash(issue.Name), dashIfEmpty(issue.SourceWorkflowID), quoteOrDash(issue.ExistingWorkflowID), + folderOrRoot(issue.ExistingParentFolderID), folderOrRoot(issue.TargetFolderID)) + case ImportIssueCredentialPolicyViolation: + line := fmt.Sprintf("%s: credential %s (%s, type %s", typ, quoteOrDash(issue.Name), dashIfEmpty(issue.SourceID), dashIfEmpty(issue.CredentialType)) + if issue.TargetID != "" { + line += fmt.Sprintf(", update of target %q", issue.TargetID) + } + return line + ") refused: " + describeViolations(issue.Violations) + } + return typ + describeScalarFields(issue.Raw) +} + +func describeViolations(violations []ImportIssueViolation) string { + if len(violations) == 0 { + return "-" + } + parts := make([]string, 0, len(violations)) + for _, violation := range violations { + part := dashIfEmpty(violation.CheckID) + ": " + dashIfEmpty(violation.Message) + if violation.OptInAvailable { + part += " (opt-in available)" + } + parts = append(parts, part) + } + return strings.Join(parts, "; ") +} + +// describeScalarFields renders the string, number, and boolean fields of an +// issue document, plus arrays of those, as sorted key=value pairs. Nulls, +// nested objects, and arrays of objects are left out. +func describeScalarFields(raw json.RawMessage) string { + var fields map[string]any + if len(raw) == 0 || json.Unmarshal(raw, &fields) != nil { + return "" + } + parts := []string{} + for _, key := range slices.Sorted(maps.Keys(fields)) { + if key == "type" { + continue + } + if value, ok := scalarText(fields[key]); ok { + parts = append(parts, key+"="+value) + continue + } + list, ok := fields[key].([]any) + if !ok || len(list) == 0 { + continue + } + items := make([]string, 0, len(list)) + for _, item := range list { + text, ok := scalarText(item) + if !ok { + items = nil + break + } + items = append(items, text) + } + if items != nil { + parts = append(parts, key+"="+strings.Join(items, ",")) + } + } + if len(parts) == 0 { + return "" + } + return ": " + strings.Join(parts, " ") +} + +func scalarText(value any) (string, bool) { + switch v := value.(type) { + case string: + return strconv.Quote(v), true + case float64: + return strconv.FormatFloat(v, 'f', -1, 64), true + case bool: + return strconv.FormatBool(v), true + } + return "", false +} + +func folderOrRoot(id *string) string { + if id == nil || *id == "" { + return "the project root" + } + return fmt.Sprintf("folder %q", *id) +} + +func quoteOrDash(value string) string { + if value == "" { + return "-" + } + return strconv.Quote(value) +} + +func dashIfEmpty(value string) string { + if value == "" { + return "-" + } + return value +} + +func joinOrDash(values []string) string { + if len(values) == 0 { + return "-" + } + return strings.Join(values, ", ") } // ImportBlockedError is a 409 (conflict) or 422 (unprocessable) import diff --git a/internal/n8n/n8n_package_test.go b/internal/n8n/n8n_package_test.go index de3a969..c86c4e5 100644 --- a/internal/n8n/n8n_package_test.go +++ b/internal/n8n/n8n_package_test.go @@ -772,3 +772,221 @@ func TestImportPackageSelectionCancellation(t *testing.T) { t.Errorf("error = %v, want context.Canceled", err) } } + +func TestImportPackageCredentialConflictPolicy(t *testing.T) { + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, packageImportResultJSON)) + client := server.client(t) + + for _, policy := range []string{ImportCredentialConflictKeep, ImportCredentialConflictOverwrite, ImportCredentialConflictFail} { + _, err := client.ImportPackage(context.Background(), ImportPackageRequest{ + WorkflowConflictPolicy: ImportWorkflowConflictSkip, + WorkflowIDPolicy: ImportWorkflowIDSource, + CredentialConflict: policy, + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if err != nil { + t.Fatalf("ImportPackage(%s): %v", policy, err) + } + req, raw := server.last(t) + fields, _, _ := parseMultipartImport(t, req, []byte(raw)) + if fields["credentialConflictPolicy"] != policy { + t.Errorf("credentialConflictPolicy = %q, want %q", fields["credentialConflictPolicy"], policy) + } + } + + _, err := client.ImportPackage(context.Background(), ImportPackageRequest{ + WorkflowConflictPolicy: ImportWorkflowConflictSkip, + WorkflowIDPolicy: ImportWorkflowIDSource, + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if err != nil { + t.Fatalf("ImportPackage(unset): %v", err) + } + req, raw := server.last(t) + fields, _, _ := parseMultipartImport(t, req, []byte(raw)) + if _, sent := fields["credentialConflictPolicy"]; sent { + t.Errorf("credentialConflictPolicy = present, want omitted when unset for older instances") + } + + before := len(server.requests) + _, err = client.ImportPackage(context.Background(), ImportPackageRequest{ + WorkflowConflictPolicy: ImportWorkflowConflictSkip, + WorkflowIDPolicy: ImportWorkflowIDSource, + CredentialConflict: "replace", + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if err == nil || !strings.Contains(err.Error(), "credential-conflict policy") || !strings.Contains(err.Error(), "keep-existing, overwrite, fail") { + t.Errorf("error = %v, want the unknown policy named with the allowed values", err) + } + if len(server.requests) != before { + t.Errorf("requests = %d, want %d: validation runs before transport", len(server.requests), before) + } +} + +func TestImportPackageResultCredentialsUpdated(t *testing.T) { + body := `{ + "package":{"sourceN8nVersion":"2.46.4","sourceId":"pkg-3","exportedAt":"2026-11-01T00:00:00.000Z"}, + "workflows":[],"removedWorkflows":[],"removedFolders":[],"folders":[],"projects":[], + "bindings":{"workflows":{},"credentials":{"c-up":"t-up"}}, + "credentials":{"matched":["c-ok"],"stubbed":[],"seeded":[],"incomplete":[],"updated":["c-up"]}, + "dataTables":{"matched":0,"created":0,"updated":0}, + "variables":{"matched":[],"missing":[],"created":[],"stubbed":[],"updated":[]}, + "tags":{"matched":[],"created":[],"renamed":[],"reconciled":[],"skipped":[]} +}` + for _, tc := range []struct { + name string + body string + want []string + }{ + {"present", body, []string{"c-up"}}, + {"absent before 2.46", packageImportResultJSON, nil}, + } { + t.Run(tc.name, func(t *testing.T) { + server := newCommunityPackageServer(t, packageJSONHandler(http.StatusOK, tc.body)) + result, err := server.client(t).ImportPackageSelection(context.Background(), ImportPackageSelectionRequest{ + ProjectID: "p", + WorkflowIDs: []string{"a"}, + WorkflowIDPolicy: ImportWorkflowIDSource, + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if err != nil { + t.Fatalf("ImportPackageSelection: %v", err) + } + if diff := cmp.Diff(tc.want, result.Credentials.Updated); diff != "" { + t.Errorf("credentials.updated mismatch (-want +got):\n%s", diff) + } + encoded, err := json.Marshal(result) + if err != nil { + t.Fatalf("Marshal: %v", err) + } + if tc.want != nil && !strings.Contains(string(encoded), `"updated":["c-up"]`) { + t.Errorf("json = %s, want credentials.updated kept", encoded) + } + }) + } +} + +func TestImportBlockingIssueDescribe(t *testing.T) { + for _, tc := range []struct { + name string + raw string + want []string + }{ + { + "agent-conflict", + `{"type":"agent-conflict","kind":"task-id","sourceAgentId":"ag-1","projectId":"p1","sourceTaskId":"task-9","targetIds":["ag-x","ag-y"]}`, + []string{"agent-conflict (task-id)", `agent "ag-1"`, `task "task-9"`, `project "p1"`, "ag-x, ag-y"}, + }, + { + "agent-conflict without task", + `{"type":"agent-conflict","kind":"existing","sourceAgentId":"ag-1","projectId":"p1","targetIds":["ag-x"]}`, + []string{"agent-conflict (existing)", "matches existing agent(s) ag-x"}, + }, + { + "agent-invalid", + `{"type":"agent-invalid","sourceAgentId":"ag-2","path":"agents/ag-2.json","message":"missing model"}`, + []string{"agent-invalid", `agent "ag-2"`, "agents/ag-2.json", "missing model"}, + }, + { + "agent-dependency-unresolved", + `{"type":"agent-dependency-unresolved","sourceAgentId":"ag-3","projectId":"p1","dependencyType":"workflow","referenceId":"wf-7","path":"tools[0]","reason":"inaccessible"}`, + []string{"agent-dependency-unresolved", `agent "ag-3"`, `workflow "wf-7"`, "tools[0]", "is inaccessible"}, + }, + { + "agent-policy-violation", + `{"type":"agent-policy-violation","sourceAgentId":"ag-4","name":"Helper","violations":[{"kind":"block","checkId":"no-shell","message":"shell tool not allowed","optInAvailable":true},{"kind":"block","checkId":"model","message":"model not allowed"}]}`, + []string{"agent-policy-violation", `agent "Helper" (ag-4)`, "no-shell: shell tool not allowed (opt-in available)", "; model: model not allowed"}, + }, + { + "workflow-folder-conflict null target", + `{"type":"workflow-folder-conflict","sourceWorkflowId":"wf-1","existingWorkflowId":"wf-9","existingParentFolderId":"f-old","targetFolderId":null,"name":"Flow"}`, + []string{"workflow-folder-conflict", `workflow "Flow" (wf-1)`, `"wf-9"`, `in folder "f-old"`, "targets the project root"}, + }, + { + "workflow-folder-conflict folder target", + `{"type":"workflow-folder-conflict","sourceWorkflowId":"wf-1","existingWorkflowId":"wf-9","existingParentFolderId":null,"targetFolderId":"f-new","name":"Flow"}`, + []string{"in the project root", `targets folder "f-new"`}, + }, + { + "credential-policy-violation with target", + `{"type":"credential-policy-violation","sourceId":"c-1","targetId":"t-1","name":"Slack","credentialType":"slackApi","usedBy":[],"violations":[{"kind":"deny","checkId":"no-update","message":"updates refused"}]}`, + []string{"credential-policy-violation", `credential "Slack" (c-1, type slackApi, update of target "t-1")`, "no-update: updates refused"}, + }, + { + "credential-policy-violation without target", + `{"type":"credential-policy-violation","sourceId":"c-2","credentialType":"httpBasicAuth","usedBy":[],"violations":[{"kind":"deny","checkId":"type","message":"type not allowed"}]}`, + []string{`credential - (c-2, type httpBasicAuth) refused: type: type not allowed`}, + }, + { + "known variant renders generically", + `{"type":"workflow-conflict","sourceWorkflowId":"a","existingWorkflowId":"b","name":"Example"}`, + []string{`workflow-conflict: existingWorkflowId="b" name="Example" sourceWorkflowId="a"`}, + }, + { + "unknown variant renders generically", + `{"type":"future-thing","count":3,"ok":false,"ids":["x","y"],"nested":{"a":1},"gone":null,"usedBy":[{"id":"w"}]}`, + []string{`future-thing: count=3 ids="x","y" ok=false`}, + }, + { + "unknown variant with conflicting field shape", + `{"type":"future-thing","violations":"not-an-array","name":"N"}`, + []string{`future-thing: name="N" violations="not-an-array"`}, + }, + } { + t.Run(tc.name, func(t *testing.T) { + var issue ImportBlockingIssue + if err := json.Unmarshal([]byte(tc.raw), &issue); err != nil { + t.Fatalf("Unmarshal: %v", err) + } + got := issue.Describe() + for _, want := range tc.want { + if !strings.Contains(got, want) { + t.Errorf("Describe() = %q, want %q", got, want) + } + } + if strings.Contains(got, "null") || strings.Contains(got, "") || strings.Contains(got, "%!") { + t.Errorf("Describe() = %q, want no raw null or format noise", got) + } + encoded, err := json.Marshal(issue) + if err != nil || string(encoded) != tc.raw { + t.Errorf("Marshal = %s (error %v), want the verbatim issue", encoded, err) + } + }) + } +} + +func TestImportPackageBlockedDecodesNewIssues(t *testing.T) { + body := `{"message":"import blocked","issues":[ +{"type":"agent-conflict","kind":"id","sourceAgentId":"ag-1","projectId":"p1","targetIds":["ag-x"]}, +{"type":"workflow-folder-conflict","sourceWorkflowId":"wf-1","existingWorkflowId":"wf-9","existingParentFolderId":null,"targetFolderId":null,"name":"Flow"}, +{"type":"credential-policy-violation","sourceId":"c-1","targetId":"t-1","credentialType":"slackApi","usedBy":[],"violations":[{"kind":"deny","checkId":"x","message":"no"}]}]}` + for _, tc := range []struct { + status int + check func(error) bool + }{ + {http.StatusConflict, IsImportConflict}, + {http.StatusUnprocessableEntity, IsImportUnprocessable}, + } { + server := newCommunityPackageServer(t, packageJSONHandler(tc.status, body)) + _, err := server.client(t).ImportPackage(context.Background(), ImportPackageRequest{ + WorkflowConflictPolicy: ImportWorkflowConflictFail, + WorkflowIDPolicy: ImportWorkflowIDSource, + CredentialConflict: ImportCredentialConflictOverwrite, + }, strings.NewReader(packageArchiveBytes), "p.n8np") + if !tc.check(err) { + t.Fatalf("%d: error = %v, want a blocked error", tc.status, err) + } + blocked, _ := AsImportBlocked(err) + if len(blocked.Issues) != 3 { + t.Fatalf("%d: issues = %d, want 3", tc.status, len(blocked.Issues)) + } + if got := blocked.Issues[0].TargetIDs; len(got) != 1 || got[0] != "ag-x" { + t.Errorf("%d: agent-conflict targetIds = %v, want [ag-x]", tc.status, got) + } + if blocked.Issues[1].TargetFolderID != nil || blocked.Issues[1].ExistingParentFolderID != nil { + t.Errorf("%d: workflow-folder-conflict folders = %v, %v, want nil for the project root", tc.status, blocked.Issues[1].TargetFolderID, blocked.Issues[1].ExistingParentFolderID) + } + if blocked.Issues[2].TargetID != "t-1" || len(blocked.Issues[2].Violations) != 1 { + t.Errorf("%d: credential-policy-violation = %+v, want targetId and violations", tc.status, blocked.Issues[2]) + } + if !strings.Contains(err.Error(), "agent-conflict, workflow-folder-conflict, credential-policy-violation") { + t.Errorf("%d: error = %q, want the issue types", tc.status, err.Error()) + } + } +}