diff --git a/cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs b/cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs index e8dbd166b..2d5ced54a 100644 --- a/cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs +++ b/cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs @@ -33,7 +33,7 @@ public HelpMkDocsPackageTypeHandler(CmfPackage cmfPackage) : base(cmfPackage) { new Step(StepType.DeployFiles) { - ContentPath = "site/**", + ContentPath = "**", TargetDirectory = "/" } } @@ -105,6 +105,30 @@ public HelpMkDocsPackageTypeHandler(CmfPackage cmfPackage) : base(cmfPackage) ]; } + /// + internal override List GetContentToPack(IDirectoryInfo packageOutputDir) + { + var files = base.GetContentToPack(packageOutputDir); + var siteDirectory = fileSystem.Path.Join(CmfPackage.GetFileInfo().Directory.FullName, "site"); + + foreach (var file in files) + { + var relativePath = fileSystem.Path.GetRelativePath(siteDirectory, file.Source.FullName); + if (fileSystem.Path.IsPathRooted(relativePath) + || relativePath == ".." + || relativePath.StartsWith(".." + fileSystem.Path.DirectorySeparatorChar, StringComparison.Ordinal)) + { + continue; + } + + // DeployFiles preserves archive paths. Remove only the build output wrapper, + // keeping links between pages, assets and search files unchanged. + file.Target = fileSystem.FileInfo.New(fileSystem.Path.Join(packageOutputDir.FullName, relativePath)); + } + + return files; + } + /// /// Packs the generated MkDocs site. /// @@ -151,7 +175,7 @@ public override void RestoreDependencies(Uri[] repoUris) if (temporaryFolderForUnziping.Exists) { - // Each restored mkdocs zip unpacks site, docs and manifest. + // Each restored MkDocs zip contains the website, docs and manifest. // We only care about the docs folder var dependencyDocsFolders = fileSystem.Directory.GetDirectories(temporaryFolderForUnziping.FullName, "docs", SearchOption.AllDirectories); diff --git a/cmf-cli/resources/template_feed/help/from1200/Help.Package/cmfpackage.json b/cmf-cli/resources/template_feed/help/from1200/Help.Package/cmfpackage.json index fc2137fcf..22cd7c57a 100644 --- a/cmf-cli/resources/template_feed/help/from1200/Help.Package/cmfpackage.json +++ b/cmf-cli/resources/template_feed/help/from1200/Help.Package/cmfpackage.json @@ -9,7 +9,7 @@ "contentToPack": [ { "source": "site/**", - "target": "site" + "target": "" }, { "source": "docs/<%= $CLI_PARAM_ProjectName %>/**", diff --git a/docs/src/03-explore/commands/pack.md b/docs/src/03-explore/commands/pack.md index 514be2c5c..73a37641c 100644 --- a/docs/src/03-explore/commands/pack.md +++ b/docs/src/03-explore/commands/pack.md @@ -60,3 +60,20 @@ Name | Description + +## MES v12 MkDocs Help packages + +`cmf build` keeps MkDocs output in `site/`. When packing a v12 Help package, +`cmf pack` places the selected contents of `site/` at the archive root, preserving +all relative paths between HTML pages, assets and search files. Documentation +sources remain under `docs//` for dependency restoration. + +This also applies to existing packages whose `contentToPack` maps `site/**` to +`site`; no project-specific name or source configuration change is required. +New Help templates map `site/**` to an empty target explicitly. + +The default `DeployFiles` step uses `contentPath: "**"`, so extraction into +`/app` produces `/app/index.html`, matching the Product Help nginx configuration. +This step also includes the packaged documentation sources. If you override the +default steps, update any `site/**` filters to match the new archive layout. +Help packages for MES versions before v12 retain their existing behavior. diff --git a/tests/Specs/Pack.cs b/tests/Specs/Pack.cs index 4e0330248..6eab30b02 100644 --- a/tests/Specs/Pack.cs +++ b/tests/Specs/Pack.cs @@ -1374,8 +1374,11 @@ public void Help_v12_MkDocsPack_FailsWhenSiteWasNotBuilt() exception.Message.Should().Contain("Could not find MkDocs site"); } - [Fact] - public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist() + [Theory] + [InlineData("site")] + [InlineData("")] + [InlineData("site/features/custom-feature")] + public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist(string siteTarget) { var fileSystem = new MockFileSystem(new Dictionary { @@ -1387,21 +1390,25 @@ public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist() ""version"": ""1.0.0"", ""packageType"": ""Help"", ""contentToPack"": [ - { ""source"": ""site/**"", ""target"": ""site"" }, + { ""source"": ""site/**"", ""target"": """ + siteTarget + @""" }, { ""source"": ""docs/cmf/**"", ""target"": ""docs/cmf"" } ] }") }, { "/repo/Cmf.Custom.Help/docs/requirements.txt", new MockFileData("mkdocs-material") }, { "/repo/Cmf.Custom.Help/docs/cmf/index.md", new MockFileData("# Help") }, - { "/repo/Cmf.Custom.Help/site/index.html", new MockFileData("Help") }, - { "/repo/Cmf.Custom.Help/site/search/search_index.json", new MockFileData("{}") }, + { "/repo/Cmf.Custom.Help/site/index.html", new MockFileData("Guide") }, + { "/repo/Cmf.Custom.Help/site/search/search_index.json", new MockFileData("{\"docs\":[{\"location\":\"guide/\",\"title\":\"Guide\"}]}") }, + { "/repo/Cmf.Custom.Help/site/guide/index.html", new MockFileData("Home") }, + { "/repo/Cmf.Custom.Help/site/assets/theme.css", new MockFileData("body { background: url(images/icon.svg); }") }, + { "/repo/Cmf.Custom.Help/site/assets/images/icon.svg", new MockFileData("") }, + { "/repo/Cmf.Custom.Help/site/assets/search.js", new MockFileData("fetch('search/search_index.json')") }, { "/repo/output", new MockDirectoryData() } }); ExecutionContext.Initialize(fileSystem); var packageTypeHandler = PackageTypeFactory.GetPackageTypeHandler( - fileSystem.FileInfo.New("/repo/Cmf.Custom.Help/cmfpackage.json")) as HelpMkDocsPackageTypeHandler; + fileSystem.FileInfo.New("/repo/Cmf.Custom.Help/cmfpackage.json"), setDefaultValues: true) as HelpMkDocsPackageTypeHandler; packageTypeHandler.Pack( fileSystem.DirectoryInfo.New("/repo/package"), @@ -1411,9 +1418,28 @@ public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist() packageZip.Exists.Should().BeTrue("Package zip file should be created"); using var zip = new ZipArchive(packageZip.OpenRead(), ZipArchiveMode.Read); - zip.GetEntry("site/index.html").Should().NotBeNull(); + zip.GetEntry("index.html").Should().NotBeNull(); + zip.GetEntry("site/index.html").Should().BeNull(); zip.GetEntry("docs/cmf/index.md").Should().NotBeNull(); - zip.GetEntry("site/search/search_index.json").Should().NotBeNull(); + zip.GetEntry("search/search_index.json").Should().NotBeNull(); + + // Keep every generated file byte-for-byte, preserving relative links and search locations. + foreach (var source in fileSystem.Directory.GetFiles("/repo/Cmf.Custom.Help/site", "*", SearchOption.AllDirectories)) + { + var relativePath = fileSystem.Path.GetRelativePath("/repo/Cmf.Custom.Help/site", source).Replace('\\', '/'); + var entry = zip.GetEntry(relativePath); + entry.Should().NotBeNull(); + using var reader = new StreamReader(entry.Open()); + reader.ReadToEnd().Should().Be(fileSystem.File.ReadAllText(source)); + } + + using var manifestReader = new StreamReader(zip.GetEntry("manifest.xml").Open()); + var manifest = XDocument.Parse(manifestReader.ReadToEnd()); + var step = manifest.Descendants("step").Single(e => (string)e.Attribute("type") == "DeployFiles"); + ((string)step.Attribute("contentPath")).Should().Be("**"); + ((string)step.Attribute("targetDirectory")).Should().Be("/"); + fileSystem.File.ReadAllText("/repo/Cmf.Custom.Help/cmfpackage.json").Should().Contain("\"target\": \"" + siteTarget + "\""); + } diff --git a/tests/Specs/Restore.cs b/tests/Specs/Restore.cs index 358433243..93da38190 100644 --- a/tests/Specs/Restore.cs +++ b/tests/Specs/Restore.cs @@ -7,6 +7,7 @@ using System.IO.Abstractions.TestingHelpers; using Cmf.CLI.Core.Services; using Microsoft.Extensions.DependencyInjection; +using Moq; using tests.Objects; using Xunit; using Assert = tests.AssertWithMessage; @@ -201,8 +202,23 @@ public void RestoreDependencies_RepoNotFound() logWriter.ToString().Should().Contain("No present remote dependencies to restore. Exiting..."); } - [Fact] - public void RestoreDependencies_HelpMkDocs() + [Theory] + [InlineData(false)] + [InlineData(true)] + public void RestoreDependencies_HelpMkDocs(bool useRepositoryClients) + { + var previousServiceProvider = ExecutionContext.ServiceProvider; + try + { + RestoreDependencies_HelpMkDocsInternal(useRepositoryClients); + } + finally + { + ExecutionContext.ServiceProvider = previousServiceProvider; + } + } + + private void RestoreDependencies_HelpMkDocsInternal(bool useRepositoryClients) { var gitRepo = MockUnixSupport.Path(@"c:\test"); var ciRepo = MockUnixSupport.Path(@"c:\cirepo"); @@ -234,13 +250,19 @@ public void RestoreDependencies_HelpMkDocs() }") }, { $"{gitRepo}/requirements.txt", new MockFileData("mkdocs") }, { $"{gitRepo}/docs/other.txt", new MockFileData("original other") }, + { $"{gitRepo}/docs/LocalProject/index.md", new MockFileData("# Local project documentation") }, { $"{gitRepo}/docs/MyProject/old-file.txt", new MockFileData("old content") }, { $"{gitRepo}/docs/MyProject/index.html", new MockFileData("old index") }, { $"{ciRepo}/Cmf.Custom.Help.1.0.0.zip", new MockFileData(new DFPackageBuilder() .CreateEntry("manifest.xml", @"Cmf.Custom.Help1.0.0") + .CreateEntry("index.html", "generated website") + .CreateEntry("assets/theme.css", "body {}") + .CreateEntry("search/search_index.json", "{}") .CreateEntry("docs/MyProject/index.html", "index") .CreateEntry("docs/MyProject/getting-started.html", "getting started") .CreateEntry("docs/MyProject/reference.md", "# Reference") + .CreateEntry("docs/Features/OtherFeature/index.md", "# Feature documentation") + .CreateEntry("docs/Features/OtherFeature/assets/diagram.svg", "") .CreateEntry("docs/other.txt", "restored other") .CreateEntry("docs/assets/icon.png", "icon data") .ToByteArray()) } @@ -248,6 +270,7 @@ public void RestoreDependencies_HelpMkDocs() ExecutionContext.ServiceProvider = new ServiceCollection() .AddSingleton(new ProjectConfigService()) + .AddSingleton(Mock.Of(features => features.UseRepositoryClients == useRepositoryClients)) .AddSingleton() .BuildServiceProvider(); @@ -258,7 +281,13 @@ public void RestoreDependencies_HelpMkDocs() var handler = PackageTypeFactory.GetPackageTypeHandler(package, false); handler.Should().BeOfType(); - var repo = new UriBuilder { Scheme = Uri.UriSchemeFile, Host = "", Path = ciRepo }.Uri; + var repositoryPath = useRepositoryClients ? $"{ciRepo}/Cmf.Custom.Help.1.0.0.zip" : ciRepo; + var repo = new UriBuilder { Scheme = Uri.UriSchemeFile, Host = "", Path = repositoryPath }.Uri; + if (useRepositoryClients) + { + ExecutionContext.ServiceProvider.GetRequiredService() + .InitializeClientsForRepositories(fileSystem, new[] { repo }); + } handler.RestoreDependencies(new[] { repo }); @@ -272,10 +301,25 @@ public void RestoreDependencies_HelpMkDocs() Assert.Equal("getting started", fileSystem.FileInfo.New($"{docs}/getting-started.html").OpenText().ReadToEnd()); Assert.Equal("# Reference", fileSystem.FileInfo.New($"{docs}/reference.md").OpenText().ReadToEnd()); + Assert.Equal("# Feature documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/index.md")); + Assert.Equal("", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/assets/diagram.svg")); + Assert.Equal("# Local project documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/LocalProject/index.md")); + + // Repeated restores refresh the dependency tree while preserving local project sources. + fileSystem.File.WriteAllText($"{docs}/obsolete.md", "stale dependency page"); + handler.RestoreDependencies(new[] { repo }); + Assert.False(fileSystem.File.Exists($"{docs}/obsolete.md"), "Stale dependency pages should be removed"); + Assert.Equal("# Reference", fileSystem.File.ReadAllText($"{docs}/reference.md")); + Assert.Equal("# Local project documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/LocalProject/index.md")); + Assert.Equal("# Feature documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/index.md")); + // Verify files outside docs/tenant were not touched or restored Assert.True(fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\other.txt")).Exists, "File outside docs/tenant was removed"); Assert.Equal("original other", fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\other.txt")).OpenText().ReadToEnd()); Assert.False(fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\assets\icon.png")).Exists, "Assets folder should not be restored"); + Assert.False(fileSystem.File.Exists($"{gitRepo}/docs/index.html"), "Generated home page should not be restored as a source"); + Assert.False(fileSystem.Directory.Exists($"{gitRepo}/docs/search"), "Generated search files should not be restored"); + Assert.False(fileSystem.File.Exists($"{gitRepo}/docs/assets/theme.css"), "Generated assets should not be restored"); } } } \ No newline at end of file