Adding guides to keycloak-js

README.md

@@ -1,6 +1,42 @@
-# Keycloak-js
+# Keycloak JS
 
-Client-side JavaScript library that can be used to secure web applications and integrate them with Keycloak.
+Keycloak is an Open Source Identity and Access Management solution for modern Applications and Services.
 
-TODO
+This reporsitory contains the client-side JavaScript library that can be used to secure web applications and integrate them with Keycloak.
 
+## Help and Documentation
+
+* [Documentation](https://www.keycloak.org/documentation.html)
+* [Keycloak JavaScript adapter guide](https://www.keycloak.org/securing-apps/javascript-adapter) - The specific guide for this client
+* [User Mailing List](https://groups.google.com/g/keycloak-user) - Mailing list for help and general questions about Keycloak
+
+## Reporting Security Vulnerabilities
+
+If you've found a security vulnerability, please look at the [instructions on how to properly report it](http://www.keycloak.org/security.html)
+
+## Reporting an issue
+
+If you believe you have discovered a defect in the keycloak-js adapter please open an issue in our [Issue Tracker](https://github.com/keycloak/keycloak-js/issues).
+Please remember to provide a good summary, description as well as steps to reproduce the issue.
+The tracker can also be used for feature and enhancement requests.
+
+## Getting started
+
+To start with the keycloak-js adapter please try one of our [quickstarts](https://github.com/keycloak/keycloak-quickstarts).
+
+For more details refer to the [Keycloak Documentation](https://www.keycloak.org/documentation.html).
+
+## Contributing
+
+Before contributing to keycloak-js adapter please read our [contributing guidelines](CONTRIBUTING.md).
+
+## Other Keycloak Projects
+
+* [Keycloak](https://github.com/keycloak/keycloak) - Keycloak Server and Java adapters
+* [Keycloak QuickStarts](https://github.com/keycloak/keycloak-quickstarts) - QuickStarts for getting started with Keycloak
+* [Keycloak Docker](https://github.com/keycloak/keycloak-containers) - Docker images for Keycloak
+* [Keycloak Node.js Adapter](https://github.com/keycloak/keycloak-nodejs-connect) - Keycloak adapter for Node.js
+
+## License
+
+* [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)

guides/attributes.adoc

@@ -0,0 +1,8 @@
+:project_name: Keycloak
+:project_doc_base_url: https://www.keycloak.org/docs/latest
+:adminguide_name: Server Administration Guide
+:adminguide_name_short: Server Administration
+:adminguide_link: {project_doc_base_url}/server_admin/
+:project_product: false
+:project_community: true
+:section: guide

guides/guides.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/*
+ * Copyright 2025 Red Hat Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+import childProcess from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { Readable } from 'node:stream'
+import url from 'node:url'
+import JSZip from 'jszip'
+
+const donwloadFMPP = async (url, file) => {
+  if (!fs.existsSync(file)) {
+    console.log('Downloading fmpp from %s', url)
+    const response = await fetch(url)
+    if (!response.ok) {
+      throw new Error('Error downloading fmpp.')
+    }
+    await fs.promises.writeFile(file, Readable.fromWeb(response.body))
+  }
+}
+
+const unzipFMPP = async (targetDir, file) => {
+  console.log('Unzipping %s', file)
+  const zip = new JSZip()
+  const data = fs.readFileSync(file)
+  const contents = await zip.loadAsync(data)
+  for (const key of Object.keys(contents.files)) {
+    const name = path.join(targetDir, key)
+    const entry = zip.file(key)
+    if (entry) {
+      const content = await entry.async('nodebuffer')
+      fs.writeFileSync(name, content, name.endsWith('/bin/fmpp') ? { mode: 0o755 } : {})
+    } else if (!fs.existsSync(name)) {
+      fs.mkdirSync(name)
+    }
+  }
+}
+
+const executeFMPP = async (version, exe, sourceDir, outputDir) => {
+  const files = fs.readdirSync(sourceDir)
+  for (const file of files) {
+    const statFile = path.join(sourceDir, file)
+    const stat = fs.statSync(statFile)
+
+    if (stat.isDirectory() && file !== 'templates' && file !== 'target' && file !== 'images') {
+      console.log('Processing folder %s', statFile)
+      const outputGuideDir = path.join(outputDir, file)
+      fs.mkdirSync(outputGuideDir)
+
+      const files = fs.readdirSync(statFile)
+      const adocFiles = files.filter(el => path.extname(el) === '.adoc')
+      for (const adocFile of adocFiles) {
+        console.log('Processing file %s', adocFile)
+        const result = childProcess.spawnSync(exe, ['-S', sourceDir, '-O', outputDir,
+          '-D', 'id:' + path.parse(adocFile).name + ',version:' + version,
+          path.join(file, adocFile)])
+        if (result.error) {
+          throw result.error
+        }
+      }
+    }
+  }
+}
+
+const generateZipFromDirectory = async (zip, dir, root) => {
+  const files = fs.readdirSync(dir)
+  files.forEach(function (file) {
+    file = path.resolve(dir, file)
+    const stat = fs.statSync(file)
+    if (stat && stat.isDirectory()) {
+      generateZipFromDirectory(zip, file, root)
+    } else {
+      const filedata = fs.readFileSync(file)
+      zip.file(path.relative(root, file), filedata)
+    }
+  })
+}
+
+const generateZip = async (zip, zipFile, dir, root) => {
+  generateZipFromDirectory(zip, dir, root)
+  const data = await zip.generateAsync({
+    type: 'nodebuffer',
+    compression: 'DEFLATE',
+    compressionOptions: {
+      level: 9
+    }
+  })
+  console.log('Generating zip file %s', zipFile)
+  fs.writeFileSync(zipFile, data)
+}
+
+const main = async (version) => {
+  console.log('Generating guides for version %s', version)
+
+  const fmppUrl = 'https://sourceforge.net/projects/fmpp/files/latest/download'
+  const dir = path.dirname(url.fileURLToPath(import.meta.url))
+  const targetDir = path.join(dir, 'target')
+  const fmppZip = path.join(targetDir, 'fmpp.zip')
+  const fmppExe = path.join(targetDir, 'fmpp', 'bin', 'fmpp')
+  const prefixName = 'keycloak-js-guides'
+
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir)
+  }
+
+  let outputDir = path.join(targetDir, prefixName + '-' + version)
+  if (fs.existsSync(outputDir)) {
+    fs.rmSync(outputDir, { recursive: true })
+  }
+  fs.mkdirSync(outputDir)
+
+  outputDir = path.join(outputDir, 'generated-guides')
+  fs.mkdirSync(outputDir)
+
+  await donwloadFMPP(fmppUrl, fmppZip)
+  await unzipFMPP(targetDir, fmppZip)
+  await executeFMPP(version, fmppExe, dir, outputDir)
+
+  fs.cpSync(path.join(dir, 'images'), path.join(outputDir, 'images'), { recursive: true })
+  fs.cpSync(path.join(dir, 'attributes.adoc'), path.join(outputDir, 'attributes.adoc'))
+
+  const zipFile = path.join(targetDir, prefixName + '.zip')
+  generateZip(new JSZip(), zipFile, outputDir, targetDir)
+}
+
+if (process.argv.length !== 3) {
+  console.log('Usage: node generate.js <version>')
+  process.exit(1)
+}
+
+const version = process.argv[2]
+main(version)