com.elestrago.unity.package-tools 2.5.2 → 2.5.3

package/CAHNGELOG.md

@@ -2,6 +2,27 @@
 
 ---
 
+## [2.5.3](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.5.3)
+
+### Added
+
+- Added `PackageToolApi` with public `ExportPackageSource`, `ExportLegacyPackage`, `GenerateVersionConstants`, and config lookup methods. See `Documentation~/api.md`.
+- Added `CIUtils.ExportPackageSource`, `CIUtils.ExportLegacyPackage`, and `CIUtils.ListConfigs` batch-mode entry points. See `Documentation~/manual.md`.
+- Added `resultpath` and `exitonfinish` command-line keys that write a JSON run report and set the exit code. See `Documentation~/manual.md`.
+
+### Changed
+
+- Changed `package.json` generation to write into the config's `sourcePath`, so the exported legacy `.unityPackage` ships it too.
+- Changed the `id` command-line key to accept a package name or config asset name as well as a config id.
+- Changed `CIUtils.Generate` to exit `1` when an export fails instead of always exiting `0`.
+- Changed the inspector export buttons to call `PackageToolApi` instead of the internal `PackageTool.Tools` helpers.
+
+### Removed
+
+- Removed the generated `Assets/PackageManifest/Generated/` folder; `package.json` is written to the package source folder instead.
+
+---
+
 ## [2.5.2](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.5.2)
 
 ### Fixed

package/Documentation~/api.md

@@ -22,16 +22,19 @@ Root namespace. Hosts the `PackageManifestConfig` ScriptableObject, the editor c
 public static class CIUtils
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/CIUtils.cs:14` (md5: `916a690462c237734b0cbceb4a8d3de1`, lines: 247)
+**Source:** `Assets/Package/PackageTool/Editor/CIUtils.cs:16` (md5: `cd2c4793b021866913ac7e62029e4069`, lines: 446)
 
-Continuous-integration API for package tools.
+Continuous-integration API for package tools. Every entry point here is meant to be invoked through Unity's -executeMethod and reads its arguments as key=value command-line pairs.
 
 **Members:**
 
 | Kind | Name | Signature | Line | Summary |
 |------|------|-----------|------|---------|
-| method | `Generate` | `public static void Generate()` | 65 | Attempts to use zero or more `PackageManifestConfig` assets to generate legacy Unity packages and Unity source. |
-| method | `PrepareDll` | `public static void PrepareDll()` | 197 |  |
+| method | `Generate` | `public static void Generate()` | 73 | Attempts to use zero or more `PackageManifestConfig` assets to generate legacy Unity packages and Unity source. |
+| method | `ListConfigs` | `public static void ListConfigs()` | 196 | Writes every `PackageManifestConfig` in the project to the file passed in the 'resultpath' argument so that callers can discover which selectors are valid. |
+| method | `ExportPackageSource` | `public static void ExportPackageSource()` | 213 | Exports the package source of every selected `PackageManifestConfig`. |
+| method | `ExportLegacyPackage` | `public static void ExportLegacyPackage()` | 218 | Exports every selected `PackageManifestConfig` as a legacy unity package. |
+| method | `PrepareDll` | `public static void PrepareDll()` | 319 | Sets the platform compatibility of every plugin in the source path of the project's `PackageManifestConfig` so that editor assemblies are not shipped as runtime ones. This is a command-line entry point in its own right, so it exits the editor when running on CI. |
 
 ### EditorConstants
 
@@ -39,7 +42,7 @@ Continuous-integration API for package tools.
 internal static class EditorConstants
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/EditorConstants.cs:32` (md5: `5b132575f223010b4d75c5d1a9a76596`, lines: 125)
+**Source:** `Assets/Package/PackageTool/Editor/EditorConstants.cs:32` (md5: `76bc9384e2a242b10f03867b7015a134`, lines: 145)
 
 Internal constants and readonly fields for package tools usage.
 
@@ -54,44 +57,43 @@ Internal constants and readonly fields for package tools usage.
 | field | `ASSET_EXTENSION` | `public const string ASSET_EXTENSION` | 41 |  |
 | field | `META_EXTENSION` | `public const string META_EXTENSION` | 42 |  |
 | field | `META_FORMAT` | `public const string META_FORMAT` | 43 |  |
-| field | `GENERATED_FOLDER_NAME` | `public const string GENERATED_FOLDER_NAME` | 44 |  |
-| field | `UNITY_PACKAGE_NAME_FORMAT` | `public const string UNITY_PACKAGE_NAME_FORMAT` | 45 |  |
-| field | `EMPTY_SPACE` | `public const char EMPTY_SPACE` | 46 |  |
-| field | `UNDERSCORE` | `public const char UNDERSCORE` | 47 |  |
-| field | `GROUP_BOX` | `public const string GROUP_BOX` | 53 |  |
-| field | `EDITOR_FOLDER_ICON` | `public const string EDITOR_FOLDER_ICON` | 60 |  |
-| field | `EDITOR_FILE_ICON` | `public const string EDITOR_FILE_ICON` | 61 |  |
-| field | `PACKAGE_JSON_HEADER` | `public const string PACKAGE_JSON_HEADER` | 64 |  |
-| field | `PACKAGE_CONTENT_HEADER` | `public const string PACKAGE_CONTENT_HEADER` | 65 |  |
-| field | `PACKAGE_ACTIONS_HEADER` | `public const string PACKAGE_ACTIONS_HEADER` | 66 |  |
-| field | `SOURCE_PATHS_HEADER_LABEL` | `public const string SOURCE_PATHS_HEADER_LABEL` | 68 |  |
-| field | `SOURCE_PATH_ELEMENT_LABEL_FORMAT` | `public const string SOURCE_PATH_ELEMENT_LABEL_FORMAT` | 69 |  |
-| field | `IGNORE_PATHS_HEADER_LABEL` | `public const string IGNORE_PATHS_HEADER_LABEL` | 71 |  |
-| field | `KEYWORDS_HEADER_LABEL` | `public const string KEYWORDS_HEADER_LABEL` | 73 |  |
-| field | `KEYWORD_ELEMENT_LABEL_FORMAT` | `public const string KEYWORD_ELEMENT_LABEL_FORMAT` | 74 |  |
-| field | `DEPENDENCY_HEADER_LABEL` | `public const string DEPENDENCY_HEADER_LABEL` | 76 |  |
-| field | `DEPENDENCY_ELEMENT_LABEL_FORMAT` | `public const string DEPENDENCY_ELEMENT_LABEL_FORMAT` | 77 |  |
-| field | `GENERATE_VERSION_CONSTANTS_BUTTON_TEXT` | `public const string GENERATE_VERSION_CONSTANTS_BUTTON_TEXT` | 79 |  |
-| field | `UPDATE_PACKAGE_BUTTON_TEXT` | `public const string UPDATE_PACKAGE_BUTTON_TEXT` | 86 |  |
-| field | `EXPORT_LEGACY_PACKAGE_BUTTON_TEXT` | `public const string EXPORT_LEGACY_PACKAGE_BUTTON_TEXT` | 87 |  |
-| field | `SELECT_SOURCE_PATH_FILE_PICKER_TITLE` | `public const string SELECT_SOURCE_PATH_FILE_PICKER_TITLE` | 89 |  |
-| field | `SELECT_SOURCE_PATH_PICKER_FOLDER_TITLE` | `public const string SELECT_SOURCE_PATH_PICKER_FOLDER_TITLE` | 90 |  |
-| field | `SELECT_PACKAGE_EXPORT_PATH_PICKER_TITLE` | `public const string SELECT_PACKAGE_EXPORT_PATH_PICKER_TITLE` | 91 |  |
-| field | `SELECT_VERSION_CONSTANTS_PATH_PICKER_TITLE` | `public const string SELECT_VERSION_CONSTANTS_PATH_PICKER_TITLE` | 92 |  |
-| field | `SELECT_SAMPLES_PATH_FOLDER_TITLE` | `public const string SELECT_SAMPLES_PATH_FOLDER_TITLE` | 93 |  |
-| field | `PROGRESS_BAR_TITLE` | `public const string PROGRESS_BAR_TITLE` | 94 |  |
-| field | `PROGRESS_BAR_TITLE_LEGACY` | `public const string PROGRESS_BAR_TITLE_LEGACY` | 95 |  |
-| field | `COMPILING_PROGRESS_MESSAGE` | `public const string COMPILING_PROGRESS_MESSAGE` | 96 |  |
-| field | `FOLDER_PATH_PICKER_HEIGHT` | `public const float FOLDER_PATH_PICKER_HEIGHT` | 98 |  |
-| field | `FOLDER_PATH_PICKER_BUFFER` | `public const float FOLDER_PATH_PICKER_BUFFER` | 99 |  |
-| field | `SAMPLES_FOLDER_NAME` | `public const string SAMPLES_FOLDER_NAME` | 115 |  |
-| field | `SAMPLES_HEADER_LABEL` | `public const string SAMPLES_HEADER_LABEL` | 116 |  |
-| field | `SAMPLES_ELEMENT_LABEL_FORMAT` | `public const string SAMPLES_ELEMENT_LABEL_FORMAT` | 117 |  |
-| field | `COPY_ENTRIES_HEADER_LABEL` | `public const string COPY_ENTRIES_HEADER_LABEL` | 119 |  |
-| field | `COPY_ENTRY_ELEMENT_LABEL_FORMAT` | `public const string COPY_ENTRY_ELEMENT_LABEL_FORMAT` | 120 |  |
-| field | `COPY_ENTRY_SOURCE_LABEL` | `public const string COPY_ENTRY_SOURCE_LABEL` | 121 |  |
-| field | `COPY_ENTRY_DESTINATION_LABEL` | `public const string COPY_ENTRY_DESTINATION_LABEL` | 122 |  |
-| field | `SELECT_COPY_DESTINATION_FOLDER_PICKER_TITLE` | `public const string SELECT_COPY_DESTINATION_FOLDER_PICKER_TITLE` | 123 |  |
+| field | `UNITY_PACKAGE_NAME_FORMAT` | `public const string UNITY_PACKAGE_NAME_FORMAT` | 44 |  |
+| field | `EMPTY_SPACE` | `public const char EMPTY_SPACE` | 45 |  |
+| field | `UNDERSCORE` | `public const char UNDERSCORE` | 46 |  |
+| field | `GROUP_BOX` | `public const string GROUP_BOX` | 52 |  |
+| field | `EDITOR_FOLDER_ICON` | `public const string EDITOR_FOLDER_ICON` | 59 |  |
+| field | `EDITOR_FILE_ICON` | `public const string EDITOR_FILE_ICON` | 60 |  |
+| field | `PACKAGE_JSON_HEADER` | `public const string PACKAGE_JSON_HEADER` | 63 |  |
+| field | `PACKAGE_CONTENT_HEADER` | `public const string PACKAGE_CONTENT_HEADER` | 64 |  |
+| field | `PACKAGE_ACTIONS_HEADER` | `public const string PACKAGE_ACTIONS_HEADER` | 65 |  |
+| field | `SOURCE_PATHS_HEADER_LABEL` | `public const string SOURCE_PATHS_HEADER_LABEL` | 67 |  |
+| field | `SOURCE_PATH_ELEMENT_LABEL_FORMAT` | `public const string SOURCE_PATH_ELEMENT_LABEL_FORMAT` | 68 |  |
+| field | `IGNORE_PATHS_HEADER_LABEL` | `public const string IGNORE_PATHS_HEADER_LABEL` | 70 |  |
+| field | `KEYWORDS_HEADER_LABEL` | `public const string KEYWORDS_HEADER_LABEL` | 72 |  |
+| field | `KEYWORD_ELEMENT_LABEL_FORMAT` | `public const string KEYWORD_ELEMENT_LABEL_FORMAT` | 73 |  |
+| field | `DEPENDENCY_HEADER_LABEL` | `public const string DEPENDENCY_HEADER_LABEL` | 75 |  |
+| field | `DEPENDENCY_ELEMENT_LABEL_FORMAT` | `public const string DEPENDENCY_ELEMENT_LABEL_FORMAT` | 76 |  |
+| field | `GENERATE_VERSION_CONSTANTS_BUTTON_TEXT` | `public const string GENERATE_VERSION_CONSTANTS_BUTTON_TEXT` | 78 |  |
+| field | `UPDATE_PACKAGE_BUTTON_TEXT` | `public const string UPDATE_PACKAGE_BUTTON_TEXT` | 85 |  |
+| field | `EXPORT_LEGACY_PACKAGE_BUTTON_TEXT` | `public const string EXPORT_LEGACY_PACKAGE_BUTTON_TEXT` | 86 |  |
+| field | `SELECT_SOURCE_PATH_FILE_PICKER_TITLE` | `public const string SELECT_SOURCE_PATH_FILE_PICKER_TITLE` | 88 |  |
+| field | `SELECT_SOURCE_PATH_PICKER_FOLDER_TITLE` | `public const string SELECT_SOURCE_PATH_PICKER_FOLDER_TITLE` | 89 |  |
+| field | `SELECT_PACKAGE_EXPORT_PATH_PICKER_TITLE` | `public const string SELECT_PACKAGE_EXPORT_PATH_PICKER_TITLE` | 90 |  |
+| field | `SELECT_VERSION_CONSTANTS_PATH_PICKER_TITLE` | `public const string SELECT_VERSION_CONSTANTS_PATH_PICKER_TITLE` | 91 |  |
+| field | `SELECT_SAMPLES_PATH_FOLDER_TITLE` | `public const string SELECT_SAMPLES_PATH_FOLDER_TITLE` | 92 |  |
+| field | `PROGRESS_BAR_TITLE` | `public const string PROGRESS_BAR_TITLE` | 93 |  |
+| field | `PROGRESS_BAR_TITLE_LEGACY` | `public const string PROGRESS_BAR_TITLE_LEGACY` | 94 |  |
+| field | `COMPILING_PROGRESS_MESSAGE` | `public const string COMPILING_PROGRESS_MESSAGE` | 95 |  |
+| field | `FOLDER_PATH_PICKER_HEIGHT` | `public const float FOLDER_PATH_PICKER_HEIGHT` | 97 |  |
+| field | `FOLDER_PATH_PICKER_BUFFER` | `public const float FOLDER_PATH_PICKER_BUFFER` | 98 |  |
+| field | `SAMPLES_FOLDER_NAME` | `public const string SAMPLES_FOLDER_NAME` | 135 |  |
+| field | `SAMPLES_HEADER_LABEL` | `public const string SAMPLES_HEADER_LABEL` | 136 |  |
+| field | `SAMPLES_ELEMENT_LABEL_FORMAT` | `public const string SAMPLES_ELEMENT_LABEL_FORMAT` | 137 |  |
+| field | `COPY_ENTRIES_HEADER_LABEL` | `public const string COPY_ENTRIES_HEADER_LABEL` | 139 |  |
+| field | `COPY_ENTRY_ELEMENT_LABEL_FORMAT` | `public const string COPY_ENTRY_ELEMENT_LABEL_FORMAT` | 140 |  |
+| field | `COPY_ENTRY_SOURCE_LABEL` | `public const string COPY_ENTRY_SOURCE_LABEL` | 141 |  |
+| field | `COPY_ENTRY_DESTINATION_LABEL` | `public const string COPY_ENTRY_DESTINATION_LABEL` | 142 |  |
+| field | `SELECT_COPY_DESTINATION_FOLDER_PICKER_TITLE` | `public const string SELECT_COPY_DESTINATION_FOLDER_PICKER_TITLE` | 143 |  |
 
 ### MenuItems
 
@@ -101,6 +103,12 @@ internal static class MenuItems
 
 **Source:** `Assets/Package/PackageTool/Editor/MenuItems.cs:6` (md5: `589a3e2956a9873db82d9d8193237c25`, lines: 11)
 
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | `OpenAboutModalDialog` | `internal static void OpenAboutModalDialog()` | 9 |  |
+
 ### PackageManifestConfig
 
 ```csharp
@@ -160,6 +168,7 @@ Describes a dependency that this package requires.
 |------|------|-----------|------|---------|
 | field | `packageName` | `public string packageName` | 48 | The name of the dependent package. |
 | field | `packageVersion` | `public string packageVersion` | 53 | The semantic version of the dependent package in MAJOR.MINOR.PATCH format. |
+| method | `IsEmpty` | `public bool IsEmpty()` | 55 |  |
 
 ### PackageManifestConfig.Author
 
@@ -199,6 +208,7 @@ Describes the samples of this package.
 | field | `displayName` | `public string displayName` | 76 |  |
 | field | `description` | `public string description` | 77 |  |
 | field | `folderName` | `public string folderName` | 78 |  |
+| method | `IsEmpty` | `public bool IsEmpty()` | 80 |  |
 
 ### PackageManifestConfig.CopyEntry
 
@@ -217,6 +227,29 @@ Describes a copy operation that mirrors a source file or folder into a destinati
 |------|------|-----------|------|---------|
 | field | `sourcePath` | `public string sourcePath` | 94 |  |
 | field | `destinationPath` | `public string destinationPath` | 95 |  |
+| method | `IsEmpty` | `public bool IsEmpty()` | 97 |  |
+
+### PackageToolApi
+
+```csharp
+public static class PackageToolApi
+```
+
+**Source:** `Assets/Package/PackageTool/Editor/PackageToolApi.cs:13` (md5: `0ffaac5410b567b5776ec8ca264e8b1c`, lines: 141)
+
+Public entry points for driving the package tools from other editor code. Every method throws on failure and returns the path of what it produced.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | `GetConfigs` | `public static PackageManifestConfig[] GetConfigs()` | 18 | Returns all `PackageManifestConfig` assets in the project. |
+| method | `FindConfig` | `public static PackageManifestConfig FindConfig(string selector)` | 26 | Returns the `PackageManifestConfig` matching `selector`, which is compared case-insensitively against the config id, the package name and the asset name, in that order. Returns null when nothing matches and throws when the selector is ambiguous. |
+| method | `FindConfig` | `public static PackageManifestConfig FindConfig(string selector, PackageManifestConfig[] configs)` | 35 | Returns the `PackageManifestConfig` matching `selector` from `configs`. Use this overload to resolve several selectors against a single lookup of the project. |
+| method | `GetConfig` | `public static PackageManifestConfig GetConfig(string selector)` | 63 | Returns the `PackageManifestConfig` matching `selector` and throws when no config matches it. |
+| method | `GenerateVersionConstants` | `public static string GenerateVersionConstants(PackageManifestConfig config)` | 78 | Generates the VersionConstants.cs file for `config` and returns its path, or null when the config has no version constants path set. |
+| method | `ExportPackageSource` | `public static string ExportPackageSource(PackageManifestConfig config, string version = null)` | 94 | Exports the package source of `config` to its `packageDestinationPath` and returns the path of the written package.json. When `version` is set it replaces the version on the config asset before the export. |
+| method | `ExportLegacyPackage` | `public static string ExportLegacyPackage(PackageManifestConfig config, string version = null)` | 112 | Exports `config` as a legacy unity package to its `legacyPackageDestinationPath` and returns the path of the written file. When `version` is set it replaces the version on the config asset before the export. |
 
 ## `PackageTool.Drawers`
 
@@ -304,7 +337,7 @@ public class SamplePropertyDrawer : PropertyDrawer
 internal sealed class PackageManifestConfigInspector : UnityEditor.Editor
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/Inspectors/PackageManifestConfigInspector.cs:33` (md5: `5dd7983f41776356a8288b1f1505579b`, lines: 435)
+**Source:** `Assets/Package/PackageTool/Editor/Inspectors/PackageManifestConfigInspector.cs:34` (md5: `ea2aafac6ce8a6f797db26221eaf0003`, lines: 448)
 **Attributes:** `[CustomEditor(typeof(PackageManifestConfig))]`
 **Base:** `UnityEditor.Editor`
 
@@ -312,19 +345,68 @@ internal sealed class PackageManifestConfigInspector : UnityEditor.Editor
 
 | Kind | Name | Signature | Line | Summary |
 |------|------|-----------|------|---------|
-| method | `OnInspectorGUI` | `public override void OnInspectorGUI()` | 126 |  |
+| method | `OnInspectorGUI` | `public override void OnInspectorGUI()` | 127 |  |
 
 ## `PackageTool.Tools`
 
 Stateless helpers used during export and code generation: file copy, git probing, command-line parsing, code emission, GUI layout primitives, and the `PackageJsonModel` DTO.
 
+### CIResultModel
+
+```csharp
+internal sealed class CIResultModel
+```
+
+**Source:** `Assets/Package/PackageTool/Editor/Tools/CIResultModel.cs:13` (md5: `eb350c4071447903e5aae55a66cbab71`, lines: 107)
+
+The outcome of processing a single `PackageManifestConfig` during a command-line run. Serialized to the file passed in the 'resultpath' argument so that callers do not have to parse the Unity log.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | `CreateForConfig` | `public static CIResultModel CreateForConfig(string selector, PackageManifestConfig config)` | 26 |  |
+| method | `CreateFailure` | `public static CIResultModel CreateFailure(string selector, string error)` | 39 |  |
+
+### CIConfigModel
+
+```csharp
+internal sealed class CIConfigModel
+```
+
+**Source:** `Assets/Package/PackageTool/Editor/Tools/CIResultModel.cs:53` (md5: `eb350c4071447903e5aae55a66cbab71`, lines: 107)
+
+Describes a `PackageManifestConfig` in the project for command-line callers.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | `CreateFromConfig` | `public static CIConfigModel CreateFromConfig(PackageManifestConfig config)` | 64 |  |
+
+### CIResultTools
+
+```csharp
+internal static class CIResultTools
+```
+
+**Source:** `Assets/Package/PackageTool/Editor/Tools/CIResultModel.cs:83` (md5: `eb350c4071447903e5aae55a66cbab71`, lines: 107)
+
+Helper methods for writing command-line result files.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | `WriteResultFile` | `public static void WriteResultFile<T>(string resultPath, IReadOnlyList<T> results)` | 87 |  |
+
 ### CodeGenTools
 
 ```csharp
 internal static class CodeGenTools
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/Tools/CodeGenTools.cs:36` (md5: `356a55ac25c4c9b3b20843cfb51bd73d`, lines: 145)
+**Source:** `Assets/Package/PackageTool/Editor/Tools/CodeGenTools.cs:36` (md5: `05a517ea12ca802914f3001ddd4b9dd2`, lines: 151)
 
 Helper methods for code-gen.
 
@@ -332,15 +414,15 @@ Helper methods for code-gen.
 
 | Kind | Name | Signature | Line | Summary |
 |------|------|-----------|------|---------|
-| method | `GenerateVersionConstants` | `public static void GenerateVersionConstants(PackageManifestConfig config)` | 114 |  |
+| method | `GenerateVersionConstants` | `public static string GenerateVersionConstants(PackageManifestConfig config)` | 118 | Writes the VersionConstants.cs file for `config` and returns its path, or null when the config has no output path set. |
 
 ### CommandLineTools
 
 ```csharp
-public static class CommandLineTools
+internal static class CommandLineTools
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/Tools/CommandLineTools.cs:33` (md5: `7ab75783e17ff23d3cc1d74328c58b75`, lines: 68)
+**Source:** `Assets/Package/PackageTool/Editor/Tools/CommandLineTools.cs:33` (md5: `f156fd2327465191feb0327c0a335af3`, lines: 68)
 
 Helper methods for command-line usage
 
@@ -356,7 +438,7 @@ Helper methods for command-line usage
 internal static class FileTools
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/Tools/FileTools.cs:38` (md5: `7fd9c0eb3de4e293bca7dd1aca305340`, lines: 445)
+**Source:** `Assets/Package/PackageTool/Editor/Tools/FileTools.cs:38` (md5: `724af228e6077a5540ffd4754f2d30d7`, lines: 475)
 
 Helper methods for dealing with files/directories
 
@@ -365,11 +447,13 @@ Helper methods for dealing with files/directories
 | Kind | Name | Signature | Line | Summary |
 |------|------|-----------|------|---------|
 | method | `ConvertToRelativePath` | `public static string ConvertToRelativePath(string fullFilePath, string referencePath)` | 46 | Converts `fullFilePath` into a relative file path from `referencePath`. |
-| method | `CreateOrUpdatePackageSource` | `public static void CreateOrUpdatePackageSource(PackageManifestConfig packageManifest)` | 59 | Creates or updates the existing package contents of `PackageManifestConfig` `packageManifest`. |
-| method | `CopyDocumentationToDirectory` | `public static void CopyDocumentationToDirectory(PackageManifestConfig packageManifest)` | 153 |  |
-| method | `CopyEntriesToProject` | `public static void CopyEntriesToProject(PackageManifestConfig packageManifest)` | 206 | Stages each configured `CopyEntry` into the project before the rest of the export runs. A folder source replaces the destination's contents — the destination is wiped first, then the source tree is copied in. The exception is a blank destination, which resolves to the project root and merges instead (same-named files overwritten, unrelated files left alone) to avoid wiping the repo. A file source overwrites `destination/{filename}`. A non-blank destination that does not yet exist is created. Missing sources log a warning and are skipped. |
-| method | `IsFile` | `public static bool IsFile(string path)` | 340 | Returns true if the `path` is for a file, otherwise false. |
-| method | `GetAllFilesRecursively` | `internal static IEnumerable<string> GetAllFilesRecursively(string folderPath)` | 428 | Recursive find all files starting at root folder at path `folderPath` and return a list of absolute paths to those files. |
+| method | `CreateOrUpdatePackageSource` | `public static void CreateOrUpdatePackageSource(PackageManifestConfig packageManifest)` | 60 | Creates or updates the existing package contents of `PackageManifestConfig` `packageManifest`. Failures are logged rather than thrown; callers that need to know the outcome should use `CreateOrUpdatePackageSourceOrThrow` instead. |
+| method | `CreateOrUpdatePackageSourceOrThrow` | `public static string CreateOrUpdatePackageSourceOrThrow(PackageManifestConfig packageManifest)` | 79 | Creates or updates the existing package contents of `PackageManifestConfig` `packageManifest` and returns the path of the written package.json in the destination folder. Any failure is thrown to the caller. |
+| method | `WritePackageJsonToSource` | `public static string WritePackageJsonToSource(PackageManifestConfig packageManifest)` | 151 | Writes the generated package.json of `packageManifest` into its `sourcePath` and imports it so a meta file is created for it. Returns the project-relative asset path of the written file. |
+| method | `CopyDocumentationToDirectory` | `public static void CopyDocumentationToDirectory(PackageManifestConfig packageManifest)` | 183 |  |
+| method | `CopyEntriesToProject` | `public static void CopyEntriesToProject(PackageManifestConfig packageManifest)` | 236 | Stages each configured `CopyEntry` into the project before the rest of the export runs. A folder source replaces the destination's contents — the destination is wiped first, then the source tree is copied in. The exception is a blank destination, which resolves to the project root and merges instead (same-named files overwritten, unrelated files left alone) to avoid wiping the repo. A file source overwrites `destination/{filename}`. A non-blank destination that does not yet exist is created. Missing sources log a warning and are skipped. |
+| method | `IsFile` | `public static bool IsFile(string path)` | 370 | Returns true if the `path` is for a file, otherwise false. |
+| method | `GetAllFilesRecursively` | `internal static IEnumerable<string> GetAllFilesRecursively(string folderPath)` | 458 | Recursive find all files starting at root folder at path `folderPath` and return a list of absolute paths to those files. |
 
 ### GUILayoutTools
 
@@ -394,10 +478,10 @@ Helper methods for Unity Editor GUI.
 ### GitTools
 
 ```csharp
-public static class GitTools
+internal static class GitTools
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/Tools/GitTools.cs:33` (md5: `28905c1ccedf24ceeccd78f8d8403ac2`, lines: 66)
+**Source:** `Assets/Package/PackageTool/Editor/Tools/GitTools.cs:33` (md5: `342265cbd96cf42e8b182eafccd76bf4`, lines: 60)
 
 Helper methods for retrieving git information
 
@@ -405,9 +489,8 @@ Helper methods for retrieving git information
 
 | Kind | Name | Signature | Line | Summary |
 |------|------|-----------|------|---------|
-| method | `Run` | `public static string Run(string cmd)` | 37 |  |
-| method | `GetBranch` | `public static string GetBranch()` | 56 |  |
-| method | `GetLongHeadHash` | `public static string GetLongHeadHash()` | 61 |  |
+| method | `GetBranch` | `public static string GetBranch()` | 37 |  |
+| method | `GetLongHeadHash` | `public static string GetLongHeadHash()` | 39 |  |
 
 ### PackageJsonModel
 
@@ -478,7 +561,7 @@ Helper methods for the Package Manifest Tools
 internal static class UnityFileTools
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/Tools/UnityFileTools.cs:36` (md5: `defcab177b5aef78d56ff900f7fd5555`, lines: 132)
+**Source:** `Assets/Package/PackageTool/Editor/Tools/UnityFileTools.cs:37` (md5: `3781c83065550e95be5e13cc681a57ea`, lines: 146)
 
 Helper methods for dealing with files/directories in the Unity Assets folder.
 
@@ -486,7 +569,7 @@ Helper methods for dealing with files/directories in the Unity Assets folder.
 
 | Kind | Name | Signature | Line | Summary |
 |------|------|-----------|------|---------|
-| method | `CompileLegacyPackage` | `public static void CompileLegacyPackage(PackageManifestConfig config)` | 43 | Gather all of the files/folders for the package and export them to the pre-defined location at `legacyPackageDestinationPath`. |
+| method | `CompileLegacyPackage` | `public static string CompileLegacyPackage(PackageManifestConfig config)` | 45 | Gather all of the files/folders for the package and export them to the pre-defined location at `legacyPackageDestinationPath`. Returns the path of the exported unity package. |
 
 ## `PackageTool.Utils.PackageInitialize`
 
@@ -495,18 +578,25 @@ The `Init Package` flow — `EditorWindow`, scaffold logic, and template strings
 ### PackageInitializeTemplates
 
 ```csharp
-public static class PackageInitializeTemplates
+internal static class PackageInitializeTemplates
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/Utils/PackageInitialize/PackageInitializeTemplates.cs:5` (md5: `b5c41fe3faf6bf6738eec298ef37a51d`, lines: 109)
+**Source:** `Assets/Package/PackageTool/Editor/Utils/PackageInitialize/PackageInitializeTemplates.cs:5` (md5: `5ff8dced4d4df349b62061f1a44b705b`, lines: 109)
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | `CreateChangelog` | `public static string CreateChangelog(string homepage)` | 7 |  |
+| method | `CreateLicense` | `public static string CreateLicense(string authorName)` | 87 |  |
 
 ### PackageInitializeUtil
 
 ```csharp
-public static class PackageInitializeUtil
+internal static class PackageInitializeUtil
 ```
 
-**Source:** `Assets/Package/PackageTool/Editor/Utils/PackageInitialize/PackageInitializeUtil.cs:7` (md5: `28d7079059d3379039c46b76c55dda71`, lines: 106)
+**Source:** `Assets/Package/PackageTool/Editor/Utils/PackageInitialize/PackageInitializeUtil.cs:7` (md5: `98c365daad6bf5c335a9a73365be76b6`, lines: 106)
 
 **Members:**
 

package/Documentation~/examples/ciutils-exportlegacypackage.md

@@ -0,0 +1,32 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: CIUtils.ExportLegacyPackage
+
+**Kind:** static-method
+
+**Entry point:** [CIUtils](../api.md#ciutils)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:218`
+
+## What it does
+
+Batch-mode entry point that exports only the legacy `.unitypackage`, delegating to [PackageToolApi.ExportLegacyPackage](../api.md#packagetoolapi). It takes the same arguments as [CIUtils.ExportPackageSource](../api.md#ciutils) and writes the same result file, so a caller can distribute a `.unitypackage` without also rebuilding the UPM layout. The exported archive includes the generated `package.json`, so importing it into a project yields a valid package manifest.
+
+## Snippet
+
+```bash
+"$UNITY_PATH" \
+  -batchmode \
+  -quit \
+  -projectPath "$PROJECT_PATH" \
+  -executeMethod PackageTool.CIUtils.ExportLegacyPackage \
+  id=com.elestrago.unity.package-tools \
+  resultpath=/tmp/package-tool-result.json \
+  -logFile -
+```
+
+## Observable effect
+
+- `<legacyPackageDestinationPath>/<DisplayName>_v<version>.unityPackage` is written.
+- `/tmp/package-tool-result.json` reports `legacyPackagePath` for each processed config.
+- The editor exits `0`/`1` when the `CI` environment variable is set or `exitonfinish=true` is passed.

package/Documentation~/examples/ciutils-exportpackagesource.md

@@ -0,0 +1,38 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: CIUtils.ExportPackageSource
+
+**Kind:** static-method
+
+**Entry point:** [CIUtils](../api.md#ciutils)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:213`
+
+## What it does
+
+Batch-mode entry point that exports only the package source — the headless counterpart of the **Export Package Source** inspector button, and the one to reach for when a tool outside Unity (a script, an MCP server, a release job) needs to trigger an export. It reads `id`, `version`, `generateversionconstants`, `resultpath` and `exitonfinish` as `key=value` command-line pairs, delegates the work to [PackageToolApi.ExportPackageSource](../api.md#packagetoolapi), and writes a JSON report before exiting. Unlike [CIUtils.Generate](../api.md#ciutils), a selector that matches no config is a failure here, not a warning.
+
+## Snippet
+
+```bash
+# The id selector accepts a config guid, the package name, or the config asset name.
+"$UNITY_PATH" \
+  -batchmode \
+  -quit \
+  -projectPath "$PROJECT_PATH" \
+  -executeMethod PackageTool.CIUtils.ExportPackageSource \
+  id=com.elestrago.unity.package-tools \
+  version=2.6.0 \
+  resultpath=/tmp/package-tool-result.json \
+  -logFile -
+
+# => [{"selector":"com.elestrago.unity.package-tools","configId":"…","success":true,
+#      "packageSourcePath":"Release/package.json","error":null}]
+cat /tmp/package-tool-result.json
+```
+
+## Observable effect
+
+- `Release/` (the config's `packageDestinationPath`) is rebuilt with the exported package layout.
+- `/tmp/package-tool-result.json` holds one [CIResultModel](../api.md#ciresultmodel) entry per selector, with the written paths or the error message.
+- The editor exits `0` on success and `1` on failure when the `CI` environment variable is set or `exitonfinish=true` is passed; the result file is always written first.

package/Documentation~/examples/ciutils-generate.md

@@ -6,30 +6,33 @@
 
 **Entry point:** [CIUtils](../api.md#ciutils)
 
-**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:65`
+**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:73`
 
 ## What it does
 
-The CI entry point. Reads `id=<guid>[,<guid>...]`, `version=<semver>`, `preview=<bool>`, and `generateversionconstants=<bool>` from the command line (case-insensitive `key=value` pairs), filters the [PackageManifestConfig](../api.md#packagemanifestconfig) assets to process, optionally overrides each config's `packageVersion`, optionally runs [CodeGenTools.GenerateVersionConstants](../api.md#codegentools), and exports the package source via [FileTools.CreateOrUpdatePackageSource](../api.md#filetools). Wraps the work in `LockReloadAssemblies` + `StartAssetEditing` to avoid mid-export refreshes.
+The CI entry point, and the one the GitLab pipeline calls. Reads `id=<selector>[,<selector>...]`, `version=<semver>`, `preview=<bool>`, `generateversionconstants=<bool>`, `resultpath=<file>` and `exitonfinish=<bool>` from the command line (case-insensitive `key=value` pairs), resolves the [PackageManifestConfig](../api.md#packagemanifestconfig) assets to process, optionally overrides each config's `packageVersion`, and exports **both** the legacy package and the package source through [PackageToolApi](../api.md#packagetoolapi) for every config that has the matching output path set. Use [CIUtils.ExportPackageSource](../api.md#ciutils) or [CIUtils.ExportLegacyPackage](../api.md#ciutils) when only one of the two outputs is wanted. Wraps the work in `LockReloadAssemblies` + `StartAssetEditing` to avoid mid-export refreshes.
 
 ## Snippet
 
 ```bash
 # Headless build — call from CI after PrepareDll has fixed plugin flags.
+# Arguments are key=value pairs; the id selector takes a guid, a package name or an asset name.
 "$UNITY_PATH" \
   -batchmode \
   -quit \
   -projectPath "$PROJECT_PATH" \
   -executeMethod PackageTool.CIUtils.Generate \
-  -id ea4351b5-3f49-4afc-8996-ec7b9eb43204 \
-  -version 2.4.1 \
-  -generateversionconstants true \
+  id=com.elestrago.unity.package-tools \
+  version=2.4.1 \
+  generateversionconstants=true \
+  resultpath=/tmp/package-tool-result.json \
   -logFile -
 ```
 
 ```csharp
-// Or invoke directly from an editor script — Generate() reads -id / -version /
-// -generateversionconstants from Environment.GetCommandLineArgs itself.
+// Or invoke directly from an editor script — Generate() reads id / version /
+// generateversionconstants from Environment.GetCommandLineArgs itself. To pass explicit
+// arguments instead, call PackageToolApi.ExportPackageSource(config, version).
 PackageTool.CIUtils.Generate();
 ```
 
@@ -38,4 +41,6 @@ PackageTool.CIUtils.Generate();
 - `Release/<packageName>/` is created or updated with the exported package layout (sources, package.json, README, CHANGELOG, LICENSE, Samples~, Documentation~).
 - `Release/package.json` is rewritten with the version, dependencies, and samples block derived from the config.
 - If `generateversionconstants=true`, a new `VersionConstants.cs` is emitted at the configured path before export.
-- Console prints `[Package Tools]` lines summarizing what was processed; the editor does not exit (unlike `PrepareDll`).
+- `<legacyPackageDestinationPath>/<DisplayName>_v<version>.unityPackage` is written when the config sets a legacy destination.
+- When `resultpath` is passed, a JSON array of [CIResultModel](../api.md#ciresultmodel) entries records what each config produced.
+- Console prints `[Package Tools]` lines summarizing what was processed; the editor exits `0`/`1` when the `CI` environment variable is set or `exitonfinish=true` is passed.

package/Documentation~/examples/ciutils-listconfigs.md

@@ -0,0 +1,36 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: CIUtils.ListConfigs
+
+**Kind:** static-method
+
+**Entry point:** [CIUtils](../api.md#ciutils)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:196`
+
+## What it does
+
+Batch-mode discovery step: writes every [PackageManifestConfig](../api.md#packagemanifestconfig) in the project to the file named by `resultpath` as an array of [CIConfigModel](../api.md#ciconfigmodel) entries. Run it first from a tool that drives the exports headlessly — it reports the id, package name, asset name, version and output paths of each config, which is exactly the set of values the `id=` selector accepts.
+
+## Snippet
+
+```bash
+"$UNITY_PATH" \
+  -batchmode \
+  -quit \
+  -projectPath "$PROJECT_PATH" \
+  -executeMethod PackageTool.CIUtils.ListConfigs \
+  resultpath=/tmp/package-tool-configs.json \
+  -logFile -
+
+# => [{"id":"ea4351b5-…","name":"PackageManifestConfig",
+#      "packageName":"com.elestrago.unity.package-tools","packageVersion":"2.5.2",
+#      "sourcePath":"Assets/Package/PackageTool","packageDestinationPath":"Release", …}]
+cat /tmp/package-tool-configs.json
+```
+
+## Observable effect
+
+- `/tmp/package-tool-configs.json` lists every config in the project; nothing is exported and no asset is modified.
+- The console prints `[Package Tools] Listing [N] configs in project.`
+- The editor exits `0` when the `CI` environment variable is set or `exitonfinish=true` is passed.

package/Documentation~/examples/packagetoolapi-exportlegacypackage.md

@@ -0,0 +1,39 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: PackageToolApi.ExportLegacyPackage
+
+**Kind:** static-method
+
+**Entry point:** [PackageToolApi](../api.md#packagetoolapi)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/PackageToolApi.cs:112`
+
+## What it does
+
+Exports the package as a legacy `.unitypackage` into the config's `legacyPackageDestinationPath` and returns the written file path. This is the programmatic equivalent of the **Export as Legacy Package** inspector button. The exported archive contains the package source, the documentation copies, and the generated `package.json`, so a project that imports the `.unitypackage` gets a valid manifest along with the code. Throws when the config has no `legacyPackageDestinationPath`.
+
+## Snippet
+
+```csharp
+using PackageTool;
+using UnityEditor;
+using UnityEngine;
+
+internal static class LegacyExportExample
+{
+	[MenuItem("Tools/Examples/Export Legacy Package")]
+	private static void Export()
+	{
+		var config = PackageToolApi.GetConfig("com.elestrago.unity.package-tools");
+		var unityPackagePath = PackageToolApi.ExportLegacyPackage(config);
+
+		Debug.Log($"Exported legacy package to {unityPackagePath}");
+	}
+}
+```
+
+## Observable effect
+
+- `<legacyPackageDestinationPath>/<DisplayName>_v<version>.unityPackage` is written (spaces in the display name become underscores).
+- `Assets/Package/PackageTool/package.json` is regenerated and imported before the export so the manifest is part of the archive.
+- README, CHANGELOG, LICENSE and `Documentation~/` are refreshed inside the package source folder before the archive is built.