spec-up-t 1.0.91 → 1.1.0

package/src/configure.js

@@ -0,0 +1,96 @@
+/**
+ * This script configures the Spec-Up-T Starterpack by prompting the user for input
+ * and updating the specs.json file accordingly. It performs the following tasks:
+ * 
+ * 1. Resolves the path to the specs.json file in the root directory.
+ * 2. Checks if the specs.json file exists, and exits with an error if it does not.
+ * 3. Creates a readline interface to prompt the user for input.
+ * 4. Defines a set of questions to gather information from the user.
+ * 
+ * @module configure
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// Resolve the path to specs.json in the root directory
+const JSON_FILE_PATH = path.resolve(process.cwd(), 'specs.json');
+
+// Key for accessing specs in the JSON file
+const SPECS_KEY = 'specs';
+
+// Check if the JSON file exists
+if (!fs.existsSync(JSON_FILE_PATH)) {
+    console.error(`Error: ${JSON_FILE_PATH} does not exist.`);
+    process.exit(1);
+}
+
+// Create the readline interface
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+
+// Questions for user input
+const questions = [
+    { field: 'title', prompt: 'Enter title: ', default: 'Spec-Up-T Starterpack' },
+    { field: 'description', prompt: 'Enter description: ', default: 'Create technical specifications in markdown. Based on the original Spec-Up, extended with Terminology tooling' },
+    { field: 'author', prompt: 'Enter author: ', default: 'Trust over IP Foundation' },
+    { field: 'account', prompt: 'Enter account: ', default: 'trustoverip' },
+    { field: 'repo', prompt: 'Enter repo: ', default: 'spec-up-t-starter-pack' },
+];
+
+const userResponses = {};
+
+// Function to prompt the user for inputs
+function collectUserInputs(index = 0) {
+    if (index === questions.length) {
+        rl.close();
+        applySpecFieldsToJSON();
+        return;
+    }
+
+    const { prompt, default: defaultValue } = questions[index];
+    rl.question(`${prompt} (${defaultValue}): `, (answer) => {
+        userResponses[questions[index].field] = answer || defaultValue;
+        collectUserInputs(index + 1);
+    });
+}
+
+// Function to update JSON with user-provided spec fields
+function applySpecFieldsToJSON() {
+    try {
+        const data = JSON.parse(fs.readFileSync(JSON_FILE_PATH, 'utf8'));
+
+        if (!data[SPECS_KEY] || !Array.isArray(data[SPECS_KEY]) || !data[SPECS_KEY][0]) {
+            console.error(`Error: Invalid JSON structure. "${SPECS_KEY}[0]" is missing.`);
+            process.exit(1);
+        }
+
+        // Ensure the "source" key exists in the JSON object
+        if (!data[SPECS_KEY][0].source) {
+            data[SPECS_KEY][0].source = {};
+        }
+
+        // Iterate over user responses and assign fields accordingly
+        Object.entries(userResponses).forEach(([field, value]) => {
+            if (['account', 'repo'].includes(field)) {
+                // Add these fields to the "source" key
+                data[SPECS_KEY][0].source[field] = value;
+            } else {
+                // Add all other fields to the root of the JSON object
+                data[SPECS_KEY][0][field] = value;
+            }
+        });
+
+        fs.writeFileSync(JSON_FILE_PATH, JSON.stringify(data, null, 2), 'utf8');
+        console.log(`Successfully updated ${JSON_FILE_PATH}.`);
+    } catch (error) {
+        console.error(`Error: Could not update ${JSON_FILE_PATH}.`, error.message);
+        process.exit(1);
+    }
+}
+
+// Start user input collection
+collectUserInputs();

package/src/init.js

@@ -1,25 +1,19 @@
-require('dotenv').config();
 const fs = require('fs-extra');
 const path = require('path');
-const { exec } = require('child_process');
 const outputDir = path.join(process.cwd(), 'output');
 const initFlagPath = path.join(outputDir, 'init.flag');
-let config = fs.readJsonSync(path.join(process.cwd(), 'specs.json'));
-
-const updateXTrefs = require('./get-xtrefs-data.js').updateXTrefs;
-const { prepareTref } = require('./prepare-tref');
+const collectExternalReferences = require('./collect-external-references.js').collectExternalReferences;
 
 async function initialize() {
     try {
         // Check if the init script has already run
         if (await fs.pathExists(initFlagPath)) {
-            console.log('Initialization has already been completed.');
             return;
         }
 
         // Place the init script here
         
-        updateXTrefs(process.env.GITHUB_API_TOKEN, false);
+        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/add-scripts-keys.js

@@ -0,0 +1,48 @@
+const fs = require('fs');
+const path = require('path');
+
+// Function to add scripts to package.json
+function addScriptsKeys(scriptKeys) {
+    // Path to the package.json of the project where this script is run
+    const packageJsonPath = path.resolve(__dirname, '../../../../', 'package.json');
+    // console.log('KORKOR packageJsonPath: ', packageJsonPath);
+
+    // Read the package.json file
+    fs.readFile(packageJsonPath, 'utf8', (err, data) => {
+        if (err) {
+            console.error('Error reading package.json:', err);
+            return;
+        }
+
+        try {
+            // Parse the package.json content
+            const packageJson = JSON.parse(data);
+
+            // Initialize the scripts section if it doesn't exist
+            if (!packageJson.scripts) {
+                packageJson.scripts = {};
+            }
+
+            // Add new scripts without overwriting existing ones
+            for (const [key, value] of Object.entries(scriptKeys)) {
+                if (!packageJson.scripts[key]) {
+                    packageJson.scripts[key] = value;
+                }
+            }
+
+            // Write the updated package.json back to disk
+            fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2), 'utf8', (err) => {
+                if (err) {
+                    console.error('Error writing package.json:', err);
+                } else {
+                    console.log('Scripts added to package.json successfully!');
+                }
+            });
+        } catch (parseError) {
+            console.error('Error parsing package.json:', parseError);
+        }
+    });
+}
+
+// Export the function
+module.exports = addScriptsKeys;

package/src/install-from-boilerplate/boilerplate/.env.example

@@ -0,0 +1,2 @@
+# Optional GitHub API token for increased rate limits
+GITHUB_API_TOKEN=YOUR_GITHUB_API_TOKEN

package/src/install-from-boilerplate/boilerplate/.github/workflows/fetch-and-push-xrefs.yml

@@ -0,0 +1,42 @@
+
+name: fetch and push xrefs
+
+on:
+  # push:
+  #   branches:
+  #     - main
+  workflow_dispatch:
+
+jobs:
+  build-and-deploy-spec:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+
+      - name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
+        run: |
+          echo "start install"
+          npm install
+          echo "end install"
+          echo "Spec-Up-T version:"
+          npm list spec-up-t
+          echo "start fetching xrefs"
+          node -e "require('spec-up-t/src/get-xrefs-data.js').updateXrefs()"
+          rm -rf node_modules
+      
+      - name: Commit and Push Changes
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git commit -m "Update Xrefs data via Github Action" || echo "No changes to commit"
+          git push https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }} HEAD:refs/heads/main
+
+          

package/src/install-from-boilerplate/boilerplate/.github/workflows/render-specs.yml

@@ -0,0 +1,47 @@
+
+name: spec-up-t render
+
+on:
+  # push:
+  #   branches:
+  #     - main
+  workflow_dispatch:
+
+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 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
+        run: |
+          echo "start install"
+          npm install
+          echo "end install"
+          echo "Spec-Up-T version:"
+          npm list spec-up-t
+          echo "start render"
+          node -e "require('spec-up-t')({ nowatch: true })"
+          echo "end render"
+          rm -rf node_modules
+
+      # This is a GitHub Action to deploy your static files to GitHub Pages
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3.7.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.OUTPUT_PATH }} # Use the OUTPUT_PATH environment variable
+          allow_empty_commit: true
+          force_orphan: true
+
+          

package/src/install-from-boilerplate/boilerplate/README.md

@@ -0,0 +1,3 @@
+# Documentation
+
+Read more about Spec-Up-T in the [documentation](https://trustoverip.github.io/spec-up-t-website/).

package/src/install-from-boilerplate/boilerplate/assets/test.json

@@ -0,0 +1,5 @@
+{
+  "foo": {
+    "bar": 1
+  }
+}

package/src/install-from-boilerplate/boilerplate/assets/test.text

@@ -0,0 +1 @@
+Beam me in, Scotty!

package/src/install-from-boilerplate/boilerplate/gitignore

@@ -0,0 +1,10 @@
+node_modules
+*.log
+dist
+*.bak
+*.tmp
+.DS_Store
+.env
+coverage
+build
+.history

package/src/install-from-boilerplate/boilerplate/help.txt

@@ -0,0 +1,6 @@
+===
+
+For help go to: https://trustoverip.github.io/spec-up-t-website
+
+===
+

package/src/install-from-boilerplate/boilerplate/main.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+
+# Function to handle the user's choice
+function handle_choice() {
+    local options=(
+        "Add content" "do_add_content"
+        "Render specification" "do_render"
+        "Export to PDF" "do_topdf"
+        "Collect external references (cache, faster)" "collect_external_references_cache"
+        "Collect external references (no cache, slower)" "collect_external_references_no_cache"
+        "Add, remove or view xref source" "do_add_remove_xref_source"
+        "Configure" "do_configure"
+        "Open documentation website" "do_help"
+        "Freeze specification" "do_freeze"
+    )
+
+    if [[ "$choice" =~ ^[0-8]$ ]]; then
+        local index=$((choice * 2))
+        echo -e "\n\n  ************************************"
+        echo "  ${options[index]}"
+        echo -e "  ************************************\n\n"
+        show_progress
+        ${options[index + 1]}
+    else
+        clear
+        echo -e "\n\n  ************************************"
+        echo "  Goodbye! You chose to exit."
+        echo -e "  ************************************\n\n"
+    fi
+    echo -e "\n\n\n   SPEC-UP-T: Type 'npm run menu' to return to the main menu.\n"
+}
+
+# Function to display the introduction text
+function display_intro() {
+    clear
+    cat << EOF
+
+  ,---.                  .   .        --.--
+  \`---.,---.,---.,---.   |   |,---.     |  
+      ||   ||---'|    ---|   ||   |---  |  
+  \`---'|---'\`---'\`---'   \`---'|---'     \`  
+       |                      |            
+
+  Please choose one of the following options:
+
+   [0] Add content
+   [1] Render specification
+   [2] Export to PDF
+   [3] Collect external references (cache, faster)
+   [4] Collect external references (no cache, slower)
+   [5] Add, remove or view xref source
+   [6] Configure
+   [7] Open documentation website
+   [8] Freeze specification
+   [Q] Quit
+
+   An xref is a reference to another repository.
+
+EOF
+}
+
+# Function to prompt the user for input
+function prompt_input() {
+    read -n 1 -r -p "   Enter your choice: " choice
+    echo -e "\n"
+}
+
+function do_add_content() {
+    clear
+    echo -e "\n\n\n   ********************\n\n\n   You can start adding your content to the markdown files in the "spec" directory.\n\n   You can do this by editing local files in an editor or by going to your repository on GitHub.\n\n   More info: https://trustoverip.github.io/spec-up-t-website/docs/various-roles/content-authors-guide/introduction\n\n\n   ********************"  
+}
+
+function do_render() { clear; npm run render; }
+function do_topdf() { clear; npm run topdf; }
+function collect_external_references_cache() { clear; npm run collectExternalReferencesCache; }
+function collect_external_references_no_cache() { clear; npm run collectExternalReferencesNoCache; }
+function do_add_remove_xref_source() { clear; npm run addremovexrefsource; }
+function do_configure() { clear; npm run configure; }
+function do_freeze() { clear; npm run freeze; }
+
+function do_help() {
+    clear
+    echo -e "\n\n\n   You will be redirected to the documentation website\n\n   (https://trustoverip.github.io/spec-up-t-website/)."
+    sleep 2
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        open "https://trustoverip.github.io/spec-up-t-website/"
+    elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+        xdg-open "https://trustoverip.github.io/spec-up-t-website/"
+    elif [[ "$OSTYPE" == "cygwin" || "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+        start "https://trustoverip.github.io/spec-up-t-website/"
+    else
+        echo "Unsupported OS."
+    fi
+}
+
+function show_progress() {
+    for i in {1..3}; do printf "."; sleep 0.2; done
+}
+
+# Main script
+display_intro
+prompt_input
+handle_choice