spec-up-t 1.1.14 → 1.1.16

package/.github/workflows/create-project-via-artifact.yml

@@ -0,0 +1,67 @@
+name: Create Spec-Up-T Project via Artifact
+
+# Trigger the workflow manually with an input for the project name
+on:
+  workflow_dispatch:
+    inputs:
+      project-name:
+        description: 'Name of the new project directory'
+        required: true
+      user-pat:
+        description: 'Your GitHub PAT (optional, to push to your own repo)'
+        required: false
+
+jobs:
+  create-project:
+    runs-on: ubuntu-latest
+    steps:
+      # Step 1: Check out the spec-up-t repo
+      - name: Checkout spec-up-t repository
+        uses: actions/checkout@v4
+
+      # Step 2: Set up Node.js environment
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18' # Adjust to your required Node version
+
+      # Step 3: Install npx and the spec-up-t-starter-pack package
+      - name: Install dependencies and npx package
+        run: |
+          npm install -g create-spec-up-t
+
+      # Step 4: Run the npx command with the provided project name
+      - name: Create new project from boilerplate
+        run: |
+          npx create-spec-up-t ${{ github.event.inputs.project-name }}
+
+      # Step 5: List the generated project files (for verification)
+      - name: Verify generated project
+        run: |
+          ls -la ${{ github.event.inputs.project-name }}
+
+      # Step 6: Upload the generated project as an artifact
+      - name: Upload project as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ github.event.inputs.project-name }}
+          path: ${{ github.event.inputs.project-name }}
+
+
+      - name: Push to new repository (if PAT provided)
+        if: github.event.inputs.user-pat != ''
+        env:
+            USER_PAT: ${{ github.event.inputs.user-pat }}
+        run: |
+            cd ${{ github.event.inputs.project-name }}
+            git init
+            git add .
+            git commit -m "Initial project's Spec-Up-T installation"
+            git remote add origin https://x-access-token:${{ env.USER_PAT }}@github.com/<username-from-user-or-dynamic>/${{ github.event.inputs.project-name }}.git
+            git push -u origin main
+      - name: Upload artifact (if no PAT)
+        if: github.event.inputs.user-pat == ''
+        uses: actions/upload-artifact@v4
+        with:
+            name: ${{ github.event.inputs.project-name }}
+            path: ${{ github.event.inputs.project-name }}

package/.github/workflows/create-project-via-repo-creation.yml

@@ -0,0 +1,140 @@
+name: Create Spec-Up-T Project
+
+on:
+  workflow_dispatch:
+    inputs:
+      project-name:
+        description: 'Name of the new project repository'
+        required: true
+        default: 'myproject'
+      username:
+        description: 'Your GitHub username (required if PAT is provided)'
+        required: false
+      user-pat:
+        description: 'Your GitHub PAT (optional, to push to your own repo)'
+        required: false
+
+jobs:
+  create-project:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout spec-up-t repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install create-spec-up-t
+        run: |
+          npm install -g create-spec-up-t
+
+      - name: Create new project from boilerplate
+        run: |
+          npx create-spec-up-t ${{ github.event.inputs.project-name }}
+
+      - name: Debug inputs and PAT
+        if: github.event.inputs.user-pat != ''
+        env:
+          USER_PAT: ${{ github.event.inputs.user-pat }}
+        run: |
+          echo "Username: ${{ github.event.inputs.username }}"
+          echo "Project Name: ${{ github.event.inputs.project-name }}"
+          curl -i -L -H "Authorization: token $USER_PAT" -H "Accept: application/vnd.github+json" https://api.github.com/user
+
+      - name: Create new repository
+        if: github.event.inputs.user-pat != ''
+        env:
+          USER_PAT: ${{ github.event.inputs.user-pat }}
+        run: |
+          curl -i -L \
+            -X POST \
+            -H "Authorization: token $USER_PAT" \
+            -H "Accept: application/vnd.github+json" \
+            https://api.github.com/user/repos \
+            -d '{"name":"${{ github.event.inputs.project-name }}","description":"Spec-Up-T project created via workflow","private":false}'
+
+      - name: Get repo public key
+        if: github.event.inputs.user-pat != ''
+        id: get-public-key
+        env:
+          USER_PAT: ${{ github.event.inputs.user-pat }}
+        run: |
+          RESPONSE=$(curl -L -H "Authorization: token $USER_PAT" -H "Accept: application/vnd.github+json" https://api.github.com/repos/${{ github.event.inputs.username }}/${{ github.event.inputs.project-name }}/actions/secrets/public-key)
+          echo "PUBLIC_KEY=$(echo $RESPONSE | jq -r .key)" >> $GITHUB_OUTPUT
+          echo "KEY_ID=$(echo $RESPONSE | jq -r .key_id)" >> $GITHUB_OUTPUT
+
+      # Install libsodium-wrappers locally
+      - name: Install libsodium-wrappers
+        if: github.event.inputs.user-pat != ''
+        run: |
+          npm install libsodium-wrappers
+
+      # Encrypt and set the PAT as a secret
+      - name: Set PAT as repo secret
+        if: github.event.inputs.user-pat != ''
+        env:
+          USER_PAT: ${{ github.event.inputs.user-pat }}
+        run: |
+          node -e "
+            const sodium = require('./node_modules/libsodium-wrappers');
+            (async () => {
+              await sodium.ready;
+              const publicKey = Buffer.from('${{ steps.get-public-key.outputs.PUBLIC_KEY }}', 'base64');
+              const secretValue = process.env.USER_PAT;
+              const messageBytes = Buffer.from(secretValue);
+              const encryptedBytes = sodium.crypto_box_seal(messageBytes, publicKey);
+              const encrypted = Buffer.from(encryptedBytes).toString('base64');
+              const keyId = '${{ steps.get-public-key.outputs.KEY_ID }}';
+
+              const response = await fetch('https://api.github.com/repos/${{ github.event.inputs.username }}/${{ github.event.inputs.project-name }}/actions/secrets/MY_PAT', {
+                method: 'PUT',
+                headers: {
+                  'Authorization': 'token ' + secretValue,
+                  'Accept': 'application/vnd.github+json'
+                },
+                body: JSON.stringify({
+                  encrypted_value: encrypted,
+                  key_id: keyId
+                })
+              });
+              if (response.ok) {
+                console.log('PAT stored as secret MY_PAT in the new repo');
+              } else {
+                console.error('Failed to set secret:', await response.text());
+                process.exit(1);
+              }
+            })();
+          "
+
+      - name: Configure Git identity
+        if: github.event.inputs.user-pat != ''
+        run: |
+          git config --global user.email "actions@github.com"
+          git config --global user.name "GitHub Actions"
+
+      - name: Push to new repository
+        if: github.event.inputs.user-pat != ''
+        env:
+          USER_PAT: ${{ github.event.inputs.user-pat }}
+        run: |
+          cd ${{ github.event.inputs.project-name }}
+          git init
+          git add .
+          git commit -m "Initial project's Spec-Up-T installation"
+          git branch -M main
+          git remote add origin https://x-access-token:${{ env.USER_PAT }}@github.com/${{ github.event.inputs.username }}/${{ github.event.inputs.project-name }}.git
+          git push -u origin main
+
+      - name: Output repository URL
+        if: github.event.inputs.user-pat != ''
+        run: |
+          echo "Your new Spec-Up-T project is at: https://github.com/${{ github.event.inputs.username }}/${{ github.event.inputs.project-name }}"
+
+      - name: Upload artifact (if no PAT)
+        if: github.event.inputs.user-pat == ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ github.event.inputs.project-name }}
+          path: ${{ github.event.inputs.project-name }}

package/index.js

@@ -252,77 +252,91 @@ module.exports = async function (options = {}) {
             return template.replace(/\${(.*?)}/g, (match, p1) => variables[p1.trim()]);
           }
 
-          return new Promise(async (resolve, reject) => {
-            Promise.all((spec.markdown_paths || ['spec.md']).map(_path => {
-              return fs.readFile(spec.spec_directory + _path, 'utf8').catch(e => reject(e))
-            })).then(async docs => {
-              const features = (({ source, logo }) => ({ source, logo }))(spec);
-              if (spec.external_specs && !externalReferences) {
-                externalReferences = await fetchExternalSpecs(spec);
-              }
+          const docs = await Promise.all(
+            (spec.markdown_paths || ['spec.md']).map(_path =>
+              fs.readFile(spec.spec_directory + _path, 'utf8')
+            )
+          );
+
+          const features = (({ source, logo }) => ({ source, logo }))(spec);
+          if (spec.external_specs && !externalReferences) {
+            externalReferences = await fetchExternalSpecs(spec);
+          }
 
               // Find the index of the terms-and-definitions-intro.md file
-              const termsIndex = (spec.markdown_paths || ['spec.md']).indexOf('terms-and-definitions-intro.md');
-              if (termsIndex !== -1) {
+          const termsIndex = (spec.markdown_paths || ['spec.md']).indexOf('terms-and-definitions-intro.md');
+          if (termsIndex !== -1) {
                 // Append the HTML string to the content of terms-and-definitions-intro.md. This string is used to create a div that is used to insert an alphabet index, and a div that is used as the starting point of the terminology index. The newlines are essential for the correct rendering of the markdown.
-                docs[termsIndex] += '\n\n<div id="terminology-section-utility-container"></div>\n\n<div id="terminology-section-start-h7vc6omi2hr2880"></div>\n\n<hr>\n\n';
-              }
+            docs[termsIndex] += '\n\n<div id="terminology-section-utility-container"></div>\n\n<div id="terminology-section-start-h7vc6omi2hr2880"></div>\n\n<hr>\n\n';
+          }
 
-              let doc = docs.join("\n");
+          let doc = docs.join("\n");
 
               // `doc` is markdown 
-              doc = applyReplacers(doc);
+          doc = applyReplacers(doc);
 
-              md[spec.katex ? "enable" : "disable"](katexRules);
+          md[spec.katex ? "enable" : "disable"](katexRules);
 
               // `render` is the rendered HTML
-              const render = md.render(doc);
-
-              const templateInterpolated = interpolate(template, {
-                title: spec.title,
-                description: spec.description,
-                author: spec.author,
-                toc: toc,
-                render: render,
-                assetsHead: assets.head,
-                assetsBody: assets.body,
-                assetsSvg: assets.svg,
-                features: Object.keys(features).join(' '),
-                externalReferences: JSON.stringify(externalReferences),
-                xtrefsData: xtrefsData,
-                specLogo: spec.logo,
-                specFavicon: spec.favicon,
-                specLogoLink: spec.logo_link,
-                spec: JSON.stringify(spec)
-              });
-
-              fs.writeFile(path.join(spec.destination, 'index.html'),
-                templateInterpolated, 'utf8'
-
-                , function (err, data) {
-                  if (err) {
-                    reject(err);
-                  }
-                  else {
-                    resolve();
-                  }
-                });
-              validateReferences(references, definitions, render);
-              references = [];
-              definitions = [];
-            });
+          const render = md.render(doc);
+
+          const templateInterpolated = interpolate(template, {
+            title: spec.title,
+            description: spec.description,
+            author: spec.author,
+            toc: toc,
+            render: render,
+            assetsHead: assets.head,
+            assetsBody: assets.body,
+            assetsSvg: assets.svg,
+            features: Object.keys(features).join(' '),
+            externalReferences: JSON.stringify(externalReferences),
+            xtrefsData: xtrefsData,
+            specLogo: spec.logo,
+            specFavicon: spec.favicon,
+            specLogoLink: spec.logo_link,
+            spec: JSON.stringify(spec)
           });
-        }
-        catch (e) {
-          console.error("❌ " + e);
+
+          const outputPath = path.join(spec.destination, 'index.html');
+          console.log('ℹ️ Attempting to write to:', outputPath);
+
+          // Use promisified version instead of callback
+          await fs.promises.writeFile(outputPath, templateInterpolated, 'utf8');
+          console.log(`✅ Successfully wrote ${outputPath}`);
+
+          validateReferences(references, definitions, render);
+          references = [];
+          definitions = [];
+        } catch (e) {
+          console.error("❌ Render error: " + e.message);
+          throw e;
         }
       }
 
       config.specs.forEach(spec => {
         spec.spec_directory = normalizePath(spec.spec_directory);
         spec.destination = normalizePath(spec.output_path || spec.spec_directory);
+      
+        if (!fs.existsSync(spec.destination)) {
+          try {
+            fs.mkdirSync(spec.destination, { recursive: true });
+            console.log(`✅ Created directory: ${spec.destination}`);
+          } catch (error) {
+            console.error(`❌ Failed to create directory ${spec.destination}: ${error.message}`);
+            throw error;
+          }
+        } else {
+          console.log(`ℹ️ Directory already exists: ${spec.destination}`);
+        }
 
-        fs.ensureDirSync(spec.destination);
+        try {
+          fs.ensureDirSync(spec.destination);
+          console.log(`✅ Ensured directory is ready: ${spec.destination}`);
+        } catch (error) {
+          console.error(`❌ Failed to ensure directory ${spec.destination}: ${error.message}`);
+          throw error;
+        }
 
         let assetTags = {
           svg: fs.readFileSync(modulePath + '/assets/icons.svg', 'utf8') || ''
@@ -371,17 +385,27 @@ module.exports = async function (options = {}) {
           fs.copySync(path.join(katexDist, 'fonts'), path.join(spec.destination, 'fonts'));
         }
 
+        // Run render and wait for it
+        render(spec, assetTags)
+          .then(() => {
+            console.log('ℹ️ Render completed for:', spec.destination);
+            if (options.nowatch) {
+              console.log('ℹ️ Exiting with nowatch');
+              process.exit(0);
+            }
+          })
+          .catch((e) => {
+            console.error('❌ Render failed:', e.message);
+            process.exit(1);
+          });
+        
         if (!options.nowatch) {
           gulp.watch(
             [spec.spec_directory + '**/*', '!' + path.join(spec.destination, 'index.html')],
             render.bind(null, spec, assetTags)
-          )
+          );
         }
 
-        render(spec, assetTags).then(() => {
-          if (options.nowatch) process.exit(0)
-        }).catch(() => process.exit(1));
-
       });
     } catch (error) {
       console.error(`Error during initialization or module execution: ${error.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "Technical specification drafting tool that generates rich specification documents from markdown. Forked from https://github.com/decentralized-identity/spec-up by Daniel Buchner (https://github.com/csuwildcat)",
   "main": "./index",
   "repository": {
@@ -30,7 +30,7 @@
     "diff": "^7.0.0",
     "dotenv": "^16.4.7",
     "find-pkg-dir": "^2.0.0",
-    "fs-extra": "^11.2.0",
+    "fs-extra": "^11.3.0",
     "gulp": "4.0.2",
     "gulp-clean-css": "4.3.0",
     "gulp-concat": "2.6.1",

package/src/collect-external-references.js

@@ -17,7 +17,7 @@ function collectExternalReferences(options = {}) {
     const readlineSync = require('readline-sync');
     const config = fs.readJsonSync('specs.json');
     const externalSpecsRepos = config.specs[0].external_specs;
-    const GITHUB_API_TOKEN = process.env.GITHUB_API_TOKEN;
+    const GITHUB_API_TOKEN = options.pat || process.env.GITHUB_API_TOKEN;
 
     const explanationPAT =
 `❌ No GitHub Personal Access Token (PAT) was found.
@@ -119,7 +119,7 @@ function collectExternalReferences(options = {}) {
         // Function to extend xtref objects with additional information, such as repository URL and directory information.
         function extendXTrefs(config, xtrefs) {
             if (config.specs[0].external_specs_repos) {
-                console.log("ℹ️ PLEASE NOTE: Your specs.json file is outdated (not your fault, we changed something). Use this one: https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-boilerplate/specs.json or e-mail kor@dwarshuis.com for help.");
+                console.log("ℹ️ PLEASE NOTE: Your specs.json file is outdated (not your fault, we changed something). Use this one: https://github.com/trustoverip/spec-up-t/blob/master/src/install-from-boilerplate/boilerplate/specs.json");
                 return;
             }
 

package/src/init.js

@@ -13,7 +13,6 @@ async function initialize() {
 
         // Place the init script here
         
-        collectExternalReferences(process.env.GITHUB_API_TOKEN, false);
         // prepareTref(path.join(config.specs[0].spec_directory, config.specs[0].spec_terms_directory));
 
         // End of the init script

package/src/install-from-boilerplate/boilerplate/.github/workflows/menu.yml

@@ -0,0 +1,110 @@
+name: Menu
+
+on:
+  workflow_dispatch:
+    inputs:
+      script:
+        description: 'Select the script to run'
+        type: choice
+        required: true
+        default: 'render'
+        options:
+          - edit
+          - render
+          - dev
+          - collectExternalReferencesCache
+          - collectExternalReferencesNoCache
+          - topdf
+          - freeze
+          - references
+          - help
+          - menu
+          - addremovexrefsource
+          - configure
+          - custom-update
+
+jobs:
+  build-and-deploy-spec:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v2
+        with:
+          persist-credentials: false
+
+      - name: Extract output_path from JSON
+        # TODO: .specs[0] is a hack to get the first spec. This should be fixed.
+        run: |
+          OUTPUT_PATH=$(jq -r '.specs[0].output_path' specs.json)
+          echo "OUTPUT_PATH=$OUTPUT_PATH" >> $GITHUB_ENV
+
+      - name: Install and Build 🔧
+        run: |
+          echo "start install"
+          npm install
+          echo "end install"
+          echo "Spec-Up-T version:"
+          npm list spec-up-t
+
+      - name: Run selected script
+        run: |
+          case ${{ github.event.inputs.script }} in
+            "edit")
+              node -e "require('spec-up-t')()"
+              ;;
+            "render")
+              node --no-warnings -e "require('spec-up-t/index.js')({ nowatch: true })"
+              ;;
+            "dev")
+              node -e "require('spec-up-t')({ dev: true })"
+              ;;
+            "collectExternalReferencesCache")
+              node --no-warnings -e "require('spec-up-t/src/collect-external-references.js').collectExternalReferences({cache: true})"
+              ;;
+            "collectExternalReferencesNoCache")
+              node --no-warnings -e "require('spec-up-t/src/collect-external-references.js').collectExternalReferences({cache: false})"
+              ;;
+            "topdf")
+              node -e "require('spec-up-t/src/create-pdf.js')"
+              ;;
+            "freeze")
+              node -e "require('spec-up-t/src/freeze.js')"
+              ;;
+            "references")
+              node -e "require('spec-up-t/src/references.js')"
+              ;;
+            "help")
+              cat ./node_modules/spec-up-t/src/install-from-boilerplate/help.txt
+              ;;
+            "menu")
+              bash ./node_modules/spec-up-t/src/install-from-boilerplate/menu.sh
+              ;;
+            "addremovexrefsource")
+              node --no-warnings -e "require('spec-up-t/src/add-remove-xref-source.js')"
+              ;;
+            "configure")
+              node --no-warnings -e "require('spec-up-t/src/configure.js')"
+              ;;
+            "custom-update")
+              npm update && node -e "require('spec-up-t/src/install-from-boilerplate/custom-update.js')"
+              ;;
+            *)
+              echo "Unknown script selected"
+              exit 1
+              ;;
+          esac
+
+      - name: Clean up
+        run: |
+          echo "end render"
+          rm -rf node_modules
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3.7.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.OUTPUT_PATH }}
+          allow_empty_commit: true
+          force_orphan: true