# PSConfluencePublisher

This program is a standalone publisher component for the 
[victorykit-xconfluencebuilder](https://bitbucket.org/victorykit/xconfluencebuilder) 
Sphinx extension.

It consumes, a JSON-formatted manifest of a *Sphinx build* dump generated by 
the `victorykit-xconfluencebuilder` and unidirectionally synchronizes 
pages, page ancestry, and attachments.

Publishing is supported via the Confluence Server REST API through 
[Personal Access Token (PAT) authorization](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).

## (Interchange) Manifest

The manifest consists of a *Pages* manifest and an *Attachments* manifest, which
store metadata on pages and attachments. Even though the *Pages* manifests 
(represented as array object) is expected to have the appropriate order for
publishing, where the oldest ancestral generation of pages is published before 
the youngest, this isn't trusted and the pages manifest is ordered in-place, 
through a Hoare partitioned Quick-Sort via the ``Optimize-PagesManifest`` 
function.

The manifest is treated as read/write and used for storing additional metadata
to reduce the amount of remote data retrieval. This includes hashing of page and
attachments content in addition to tracking publishing versions and remote ids.
Through a JSONSchema, it is made sure that the manifest stays consistent for
interchange with the original manifest producer system
(`victorykit-xconfluencebuilder`).

## Usage

You may install this PowerShell module via
[PowerShellGallery](https://www.powershellgallery.com).

```
PS > Install-Module victorykit.PSConfluencePublisher
```

Alternatively, you can import the module from source. In order to do that, 
clone the 
[Git repository](https://bitbucket.org/victorykit/psconfluencepublisher/src)
, change into the directory and import it.

```
PS> git clone git@bitbucket.org:victorykit/psconfluencepublisher.git
```

```
PS> # universal import statement compatible with PowerShell Core & Desktop
PS> Import-Module "src/PSConfluencePublisher.psd1"
```

Next, register your personal access token for your Confluence server instance. 
The token is stored as a *SecureString* type within the scope of the responsible
ested module (``PersonalAccessToken``). It is expected to have one Personal
Access Token per Confluence instance, per PowerShell session.

```
Register-PersonalAccessToken `
    -Host 'confluence.contoso.com' `
    -Token '123456789123456789'
```

Optionally, you may test the connectivity to your Confluence instance. The test
will try to retrieve your user profile, in order to determine whether the PAT 
authenticates, since an invalid PAT may results in anonymous authentication,
that does not return a fault HTTP status code for some REST API functions.

```
Test-Connection confluence.contoso.com
```

Now you may publish by supplying the URL of the root Confluence page 
you want to publish to, in addition to the location of the local dump manifest. 
Make sure to use the full URL, with the same hostname as the one you used to 
register your personal access token.

```
Publish-Dump `
    -Url 'https://confluence.contoso.com/display/TIARA/Testitest' `
    -DumpIndex build/docs/confluence.out/data.json
```

The manifest MUST be writable, where it is then used to cache the publishing 
status of each page and attachment.

You may publish a single page, which however requires it's direct ancestral page 
to exist.

```
Publish-Page
```

## Compatibility

This program is compatible with the following Microsoft PowerShell runtimes:

- Microsoft PowerShell Desktop >=5
- Microsoft PowerShell Core >=7

## Runtime Dependencies

This program has no runtime dependencies.

On PowerShell Desktop, however, it is necessary to obtain the 
`Microsoft.PowerShell.Utility` module for JSON schema verification of the 
manifest. Whether that's possible for PowerShell Desktop; We do not know. 
Should the aforementioned module not be present, JSON validation is skipped.

## Debugging

To display debug messages, set 
[$DebugPreference](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.3#debugpreference)
to `Continue`, or `Inquire` in your shell's *Global* scope.

## Static Code Analysis

This program requires
[PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules)
for static code analysis.

Execute `pwsh scripts/analyze.ps1` to do a static code analysis.

## Testing

This program requires [Pester](https://pester.dev/) to execute it's test suite.

The test suite aims to be executable under most circumstances. We've been 
dropping usage of Pester v5 functionalities so that it works with Pester down 
to version 3, since Pester v3 is available in PowerShell (5) Desktop by default.
Due to the security mechanisms implemented in PowerShell Desktop, installing the
Pester v5 module may not be feasible for some.

Execute `pwsh scripts/test.ps1` to run the entire test suite.

## Packaging & Publishing

This program does not adhere to Microsoft's Best-Practices of publishing
PowerShell modules, in the sense of that it does not use the *PowerShellGet*
module to do so and uses the plain `nuget` CLI instead.

This program requires [nuget
CLI](https://learn.microsoft.com/en-us/nuget/install-nuget-client-tools). Be
aware that the `dotnet nuget` CLI may not be sufficient on some platforms.

Execute `pwsh scripts/pack.ps1` to create the nuget package.

Execute `pwsh scripts/publish.ps1` to publish the nuget package to
[PowerShellGallery](https://www.powershellgallery.com).