roll-right 0.1.4 → 0.2.0

package/bin/index.js

@@ -1,94 +1,170 @@
 #!/usr/bin/env node
 
-const papa = require('../index.js')
-const {load_json_file} = require('../lib/utils')
-
-const {transfer_node_module_browser_version} = require('../lib/rr_utils')
-const {transfer_github_browser_version} = require('../lib/rr_utils')
-const {transfer_local_directory_browser_version} = require('../lib/rr_utils')
-const {port_modules} = require('../lib/mod_utils')
-
-const Phase1 = require('../lib/phase1')
-const Phase2 = require('../lib/phase2')
-//
+const fos = require('extra-file-class')()
+
+// @target -- concern's directory for receiving templates
+// @concern -- the business, app, tool, or other that is receiving a code asset into it's template, pre-staging, or staging directories
+// @kernel  -- in script processing -- e.g. [app<scripts>]/file.js   -- as special code for a concern -- here, kenerl is 'scripts'
+// @<type> -- a type specification 
+// @params< -- the intake parameter descriptions for a sub-template file -- might be of type ".smplt"
+// @list< -- parameter breakout for list entities 
+// @nothing -- allows for a conditional to create empty lines for either positive or negative conditions
+// @{}  -- configuration substitutions done before parsing a skeleton
 //
 
-var g_argv = require('minimist')(process.argv.slice(2));
-console.dir(g_argv);
-
-let g_target = g_argv._[0]
-let g_source_dir = g_argv._[1]
-if ( g_source_dir === undefined ) {
-    g_source_dir = "."
-}
-
-
-function load_config(cf_name) {
-    let path = g_source_dir + '/' + cf_name
-    return load_json_file(path)
-}
-
-
-const g_config = load_config("roll-right.json")
-papa.identify_me()
-
-// // 
-function read_data(roll_conf) {
-    try {
-        console.dir(roll_conf)
-        for ( let ky in roll_conf ) {
-            let source_spec = roll_conf[ky]
-            let kys = Object.keys(source_spec)
-            if ( kys.length ) {
-                switch ( ky ) {
-                    case "pnpm" : {
-                        transfer_node_module_browser_version(source_spec)
-                        break
-                    }
-                    case "github" : {
-                        transfer_github_browser_version(source_spec)
-                        break
-                    }
-                    case "local" : {
-                        transfer_local_directory_browser_version(source_spec)
-                        break;
-                    }
-                    default: {
-                        // plugins
-                        break;
-                    }
-
+// Minimist is a command line parsing package.
+let g_argv = require('minimist')(process.argv.slice(2));
+
+const SkelToTemplate = require('../lib/SkelToTemplate')
+const TemplatesToPreStaging = require('../lib/TemplateToPreStaging')
+const PreStagingSubsitutions = require('../lib/PreStagingSubsitutions')
+
+
+/**
+ * Addesses the use case available from the command line.
+ * 
+ * There are three cases, one for each phase of page generation starting 
+ * from the first use of skeletons and ending with final pages.
+ * 
+ * 1. prepare
+ * 2. template
+ * 3. page (also can use 'assign' as in variable assignment that ends up on the page)
+ * 
+ * 
+ * case 1:
+ *  args.phase === 'prepare'
+ *  args.sources -- directory where the generator file and other files for input and output will be found 
+ *  args.generator -- the name of the JSON file that contains the map between inputs and outputs and directory overrides.
+ *  args.structure -- where to put the intermediate parsing data for use in the next phase
+ * 
+ * Included in "package.json".scripts
+ *  "prepare" : "node bin/index.js --phase prepare --sources ../websites/template-configs/  --generator generate.json --structure parsed.json"
+ * 
+ * npm default command:
+ *  npm run prepare
+ * 
+ * CLI cmd:
+ * 
+ * roll-right --phase prepare --sources ../websites/template-configs/  --generator generate.json --structure parsed.json
+ * 
+ * case 2:
+ *  args.phase === 'template'
+ *  args.sources -- directory where the generator file and other files for input and output will be found 
+ *  args.generator -- the name of the JSON file that contains the map between inputs and outputs and directory overrides.
+ *  args.structure -- where to put the intermediate parsing data for use in the next phase
+ * 
+ * Included in "package.json".scripts
+ *  "templates" : "node bin/index.js --phase template --sources ../websites/template-configs/ --generator generate.json --structure parsed.json"
+ * 
+ * npm default command:
+ *  npm run templates
+ * 
+ * CLI cmd:
+ * 
+ * roll-right --phase template --sources ../websites/template-configs/ --generator generate.json --structure parsed.json
+ * 
+ * case 3:
+ *  args.phase === 'templates'
+ *  args.values -- name of a conf file that contains global values for the websites and other substitution information
+ * 
+ * Included in "package.json".scripts
+ *  "page" : "node bin/index.js --phase assign --sources ../websites/template-configs/ --values assignments.json"
+ * 
+ * roll-right --phase assign --sources ../websites/template-configs/ --values assignments.json
+ * 
+ * 
+ * @param {object} args - the data structure returned by minimist
+ */
+async function command_line_operations_new(args) {
+    let phase = args.phase
+    //
+    if ( phase ) {
+        //
+        console.log("Operating phase:\t\t\t\t\t", phase)
+        switch ( args.phase ) {
+            case "prepare" :
+            case 1: {                       /// creates templates
+                let project_dir = args.sources  // for instance [website]/template-configs
+                let generator = args.generator  // a string ... for instance generate.json
+                generator = `${project_dir}${generator}`
+                console.log("Using input configuration for generator:\t\t",generator)
+                //
+                let parsed = args.structure
+                parsed = `${project_dir}${parsed}`
+                console.log("Using output to configuration for template formation:\t\t",parsed)
+
+                // only works if there is a configuration file
+                let conf = await fos.load_json_data_at_path(generator)
+                if ( conf ) {
+                    conf.top_level_parsed = parsed    // path to output in the template configuration directory (use globally)
+                    let to_templates = new SkelToTemplate(conf)
+                    to_templates.set_project_directory(project_dir)
+                    await to_templates.prepare_directories()  // makes sure the output directories exists (in any case)
+                    await to_templates.skeleton_unification()        // parsing and primary evaluations
+                    await to_templates.write_templates_op_data()    // generate db files and parse data structure and output update
                 }
+                break
             }
-        }
-    } catch (e) {
-        console.log(e)
-    }
-}
-
-
-async function command_line_operations() {
-    console.log("command line operations")
-
-    if ( g_argv.phase ) {
-        console.log(`starting phase ${g_argv.phase} instantiation`)
-        switch ( g_argv.phase ) {
             case "template" :
-            case 1: {                       /// creates templates
-                if ( typeof g_config.alpha === "string" ) {
-                    g_config.alpha = load_json_file(g_config.alpha) // ALPHA
+            case 2: {
+                let project_dir = args.sources
+                let generator = args.generator  // a string
+                generator = `${project_dir}${generator}`
+                console.log("Using input configuration from generation:\t\t",generator)
+                //
+                let parsed = args.structure
+                parsed = `${project_dir}${parsed}`
+                console.log("Using input configuration for template formation:\t\t",parsed)
+                let conf = await fos.load_json_data_at_path(generator)
+                if ( conf ) {
+                    let to_templates = new SkelToTemplate(conf)
+                    to_templates.set_project_directory(project_dir)
+                    await to_templates.prepare_directories()        // needed even when loading previously parsed data.
+                    await to_templates.load_ogroups_intermediate_files()
+                    let parsed_skels = await fos.load_json_data_at_path(parsed)
+                    let concerns = false
+                    if ( parsed_skels ) {
+                        // regenerates with changes provided by custom settings developed after the prepare 
+                        // stage of the processing. This will be out of the way before any substitution 
+                        // objects are created.
+                        concerns = await to_templates.generate_all_concerns_templates(parsed_skels)
+                    } else {
+                        console.log("did not load " + parsed)
+                    }
+                    // If the customized regeneration process has succeeded, then create susbtitution 
+                    // objects. 
+                    if ( concerns ) {
+                        let to_pre_staging = new TemplatesToPreStaging(conf)
+                        to_pre_staging.set_project_directory(project_dir)
+                        let subst_defs = await to_pre_staging.prepare_files_and_substitutions(concerns)
+                        await to_pre_staging.publish_subs_defs(subst_defs)
+                    }
+                    //
                 }
-                let ph1 = new Phase1(g_target,g_config.alpha)       // g_target <- args[0] ... g_config <- read <- g_source_dir <- args[1] 
-                ph1.run()
                 break
             }
-            case "page":
-            case 2: {
-                if ( typeof g_config.beta === "string" ) {
-                    g_config.beta = load_json_file(g_config.beta)   // BETA 
+            case "page"   :
+            case "assign" :
+            case 3: {
+                //
+                let project_dir = args.sources
+                let substitutions = args.values
+                substitutions = `${project_dir}${substitutions}`
+                console.log("Using input configuration for assignments:\t\t",substitutions)
+                //
+                let conf = await fos.load_json_data_at_path(substitutions)
+                if ( conf ) {
+                    //
+                    let to_pre_staging = new PreStagingSubsitutions(conf)
+                    to_pre_staging.set_project_directory(project_dir)
+console.log(to_pre_staging.project_dir)
+                    let concerns_file = `${to_pre_staging.project_dir}/concerns_to_files.json`
+console.log("concerns file",concerns_file)
+                    let concerns = await fos.load_json_data_at_path(concerns_file)
+                    await to_pre_staging.process_files(concerns)
+                    //
                 }
-                let ph2 = new Phase2(g_target,g_config.beta)        // g_target <- args[0] ... g_config <- read <- g_source_dir <- args[1] 
-                ph2.run()
+                //
                 break
             }
             default : {
@@ -96,22 +172,34 @@ async function command_line_operations() {
                 break;
             }
         }
+        //
+    } else {
+    console.log("-------------------------------------------------------------")
+        let usage = `
+The configuration file will be found in the sources directory.
+
+phase 1:
+roll-right --phase prepare --sources <directory containing configuration files>  --generator <name of config file>.json --structure <name of file to output parsing structure>.json
+
+phase 2:
+roll-right --phase template --sources <directory containing configuration files> --generator <name of config file>.json --structure <name of file to input parsing structure>.json
+
+phase 3:
+roll-right --phase assign --sources <directory containing configuration files> --values <variable substitutions site-wide>.json
+        `
+        console.log(usage)
     }
-    if ( g_argv.gather ) {  // about moving files to directories for node module, browser modules, etc.
-        if ( typeof g_config.gather === "string" ) {
-            g_config.modules = load_json_file(g_config.gather)
-        }
-        read_data(g_config.gather)
-    }
-    if ( g_argv.modules ) {  // transforms and then copies base alpha code to final publication directores (npm is the only case yet)
-        if ( typeof g_config.modules === "string" ) {
-            g_config.modules = load_json_file(g_config.modules)
-        }
-        port_modules(g_config.modules,g_argv)
-    }
+
+    console.log("-------------------------------------------------------------")
 
 }
 
 
+console.log("-------------------------------------------------------------")
+console.log("roll-right static content management and module publication")
+console.log("-------------------------------------------------------------")
+
+// command_line_operations()
+
 
-command_line_operations()
+command_line_operations_new(g_argv)

package/docs/rr-background.md

@@ -0,0 +1,35 @@
+# roll-right background
+
+The tool is the result of having no desire to spend all day making web pages and other interfaces.
+
+This project started out as something to help save time.  Sometimes it did, sometimes work on the output progressed faster. It started out as something to keep small and generated some output web pages. Then, I edited its end results by hand. But, there is a need to propagate improvements made directly to the outputs of this tool. So, there is a need to take snippets from edge-of-the-envelope textual artifacts back into the pool of snippets the tool reads, and then use this tool again to change/upgrade all textual artifacts using the snippet repository. As a result, I revisited this project and started making something that is more like a web page compiler. Also, I have a framework for PWAs (progressive web apps) that this tool can be applied to. (The aim of this side trip is to shutdown a certain amount of interface creation labor.)
+
+Making UI components is not a bad thing to do, in fact, it's quite good. But, why should it take longer than expected? Indeed, there are minutia, weird practices by different interface communities, gotchas, and more. Something as simple in concept as CSS has turned into a strange black art sort of quagmire yielding heaps of frustration. There are so many times that CSS magic fails to get to the goal and some JavaScript has to be added. 
+
+Once a final interface goal has been reached, it's change may have been worked out for one final output page. But, a website manager may have a number of pages required as outputs. It follows that there is a huge chore (which can always be put off) to put successful changes into all the output pages an organization might manage. A small website company could end up spending countless hours taking keeping code up to date with local bug fixes. So, some better process is needed.
+
+Here, the idea is that there should be a repository of snippets and skeletons of output pages. A process requiring configuration files reflecting choices made by the user of the program, can take use the skeletons to generate outputs. Changes can be put into a common code base, skeletons can be brought up to date, choice interface markup can be stored in a repository. Then, one tool can roll the changes forward into final outputs. If users have content already made for the sites, the tool could move quickly through all phases (one run) and output updates. But, a user could also start up a new concern and add content to sections described to the user by intermediate outputs of the tool, so the user could make changes between running phases of the tool.
+
+**roll-right** works in phases. Each phase generates outputs and configurations for use in the next phase, until the final outputs are placed into a "staging" directory. In the end, the staging directory should be something that can be copied to a server directory where a web server looks for web pages and code pages.
+
+#### Composition (skeletons to templates)
+
+This tool mainly puts together snippets into final forms, files, directories. It does not attempt to know much, but is useful where replication with small differences works. That is, it is not going to be better than just copying files if that is all that has to be done. Also, it is not an automatic programming agent (at least no yet).
+
+***This tool is good at making templates that then get customization, personalization, etc. via a substitution process.***
+
+### not a component library
+
+I don't think of skeleton files as components. These are pre-temlates. The tool reads them in order to produces HTML templates. The HTML templates can have values inserted into them by tools such as [mustache](https://mustache.github.io/).
+
+The skeletons provide definitions of structure, program inclusion, etc. The skeletons keep a record of the shape of the page, the kinds of programs it run, and helps manage what should be included in the text of the page versus what should be loaded through deferred links. The output can be expected to be static in the sense that HTML (or other) does not refer to a server to rewrite its view structurally. Some of the pages I have generated include Svelte components that update when retrieving data from the server. But, the page does not become another interface, in the sense that a grid of movie choices does not turn into an editor. **roll-right** does not provide a server that generates HTML for given URL APIs. It just reads the skeletons and turns them into the pages needed by a concern. Some of those pages might include component based apps.
+
+* Components, such as the kind made with Svelte, allow for the extension of markup by adding tags with parameters. The component is expected to come with code, HTML, and CSS. The HTML within a component may use tags that are imported into the component program. In some sense, each component is a subroutine, a part of a maintained code base.
+
+* Skeletons import/generate everything that they are told to import/generate and what they import/generate becomes part of the text of the program. Skeletons refer to big chunks of code to use, numerous chunks of code, and very commonly used markup structure. All of these inclusions are part of a common code base, that a web manager maintains. The skeleton files should be fairly short, say thirty to a hundred lines, and be used to generate a few thousand lines along with bundles for components used across skeletons.
+
+Skeletons are used to generate different versions of outputs that are configured into working single page files, with some possible external links to maintained bundles. Likely, the different versions, which are different structurally, should have been proven to work so that the output generation is a selection of a view structure or program application type, rather than something to debug. 
+
+> In spite of the aim of this project, other kinds of text files can be output through the process, including programs, documents, art.
+
+If the skeleton is used to generate a component, such as the kind made using Svelte, it will first create a template in preparation for variable substitution, then it will output the artifacts for the component in a pre-staging directory (a build directory). In other words, it carries out the same process of a static HTML file to build whatever. (Depending on the glossary of directives available in a roll-right release, this may be any kind of program.) After that, the build tools for the components will have to be applied in order to finalize the component for release. 

package/historical/old_index.js

@@ -0,0 +1,95 @@
+
+const {transfer_node_module_browser_version} = require('../lib/rr_utils')
+const {transfer_local_directory_browser_version} = require('../lib/rr_utils')
+const {port_modules} = require('../lib/mod_utils')
+
+
+
+async function load_config(cf_name) {
+    let path = g_source_dir + '/' + cf_name
+    return await fos.load_json_data_at_path(path)
+}
+
+// // 
+function read_data(roll_conf) {
+    try {
+        console.dir(roll_conf)
+        for ( let ky in roll_conf ) {
+            let source_spec = roll_conf[ky]
+            let kys = Object.keys(source_spec)
+            if ( kys.length ) {
+                switch ( ky ) {
+                    case "pnpm" : {
+                        transfer_node_module_browser_version(source_spec)
+                        break
+                    }
+                    case "github" : {
+                        transfer_github_bro[skeletons]/wser_version(source_spec)
+                        break
+                    }
+                    case "local" : {
+                        transfer_local_directory_browser_version(source_spec)
+                        break;
+                    }
+                    default: {
+                        // plugins
+                        break;
+                    }
+
+                }
+            }
+        }
+    } catch (e) {
+        console.log(e)
+    }
+}
+
+
+async function command_line_operations() {
+    console.log("command line operations")
+
+    g_config = await load_config("roll-right.json")
+
+    if ( g_argv.phase ) {
+        console.log(`starting phase ${g_argv.phase} instantiation`)
+        switch ( g_argv.phase ) {
+            case "template" :
+            case 1: {                       /// creates templates
+                if ( typeof g_config.alpha === "string" ) {
+                    g_config.alpha = fos.load_json_data_at_path(g_config.alpha) // ALPHA
+                }
+                let ph1 = new Phase1(g_target,g_config.alpha)       // g_target <- args[0] ... g_config <- read <- g_source_dir <- args[1] 
+                ph1.run()
+                break
+            }
+            case "page":
+            case 2: {
+                if ( typeof g_config.beta === "string" ) {
+                    g_config.beta = fos.load_json_data_at_path(g_config.beta)   // BETA 
+                }
+                let ph2 = new Phase2(g_target,g_config.beta)        // g_target <- args[0] ... g_config <- read <- g_source_dir <- args[1] 
+                ph2.run()
+                break
+            }
+            default : {
+                console.log("unnown phase")
+                break;
+            }
+        }
+    }
+    if ( g_argv.gather ) {  // about moving files to directories for node module, browser modules, etc.
+        if ( typeof g_config.gather === "string" ) {
+            g_config.modules = fos.load_json_data_at_path(g_config.gather)
+        }
+        read_data(g_config.gather)
+    }
+    if ( g_argv.modules ) {  // transforms and then copies base alpha code to final publication directores (npm is the only case yet)
+        if ( typeof g_config.modules === "string" ) {
+            g_config.modules = fos.load_json_data_at_path(g_config.modules)
+        }
+        port_modules(g_config.modules,g_argv)
+    }
+
+}
+
+

package/index.js

@@ -3,9 +3,3 @@ const roll_right_utilities = require('./lib/rr_utils.js')
 
 
 module.exports.browser_code = roll_right_utilities.browser_code_access
-
-
-
-module.exports.identify_me = () => {
-    console.log("roll-right static content management and module publication")
-}

package/lib/PreStagingSubsitutions.js

@@ -0,0 +1,64 @@
+const TemplatesToPreStaging = require('../lib/TemplateToPreStaging')
+
+
+
+let SysUtils = require('../lib/sys_utils')
+let sys_utils = new SysUtils({
+    "tools_directory" : "./tools"
+})
+
+
+/**
+ * @class PreStagingSubsitutions
+ * 
+ * This class extends SkelToTemplate with operations specific to phase 3.
+ * 
+ * This is the page stage. All pages for all concerns are generated, using 
+ * previously generated and edited substitutions and templates. 
+ * 
+ * The final results will be in the pre-staging directory for each concern.
+ * 
+ */
+class PreStagingSubsitutions extends TemplatesToPreStaging {
+
+    /**
+     * 
+     * @param {object} conf 
+     */
+    constructor(conf) {
+        super(conf)
+    }
+
+
+    /**
+     * 
+     * This method is phase 3 method
+     * 
+     * @param {object} concerns 
+     */
+    async process_files(concerns) {
+        for ( let concern in concerns ) {
+            let concerns_dir = `[websites]/${concern}/`
+            concerns_dir = this.paths.compile_one_path(concerns_dir)
+            let targeted_files = Object.values(concerns[concern])
+            for ( let pair of targeted_files ) {
+                let keys = Object.keys(pair)
+                for ( let ky of keys ) {
+                    //
+                    let static_dir = `${concerns_dir}/static`
+                    let afile = `${concerns_dir}/${this.created_dir}${ky}`
+                    let subst_form = ky.replace(".tmplt","_html.subst")
+                    let subst_file = `${concerns_dir}/pre-staging/${subst_form}`
+                    let ofile = subst_file.replace("_html.subst",".html")
+
+console.log(afile,"-\n",subst_file,"==>\n",ofile)
+                    sys_utils.spawn_generator(subst_file,afile,ofile,static_dir)
+                }
+            }
+        }
+    }
+
+}
+
+
+module.exports = PreStagingSubsitutions