roll-right 0.0.1 → 0.1.2

package/README.md

@@ -1,26 +1,71 @@
 # roll-right
 
- A helper utilty for gather browser artifacts from node modules, code repositories, etc.
+A command line tool that gathers selected code components from curated bases of code and that, first, fans them into templates for site pages and that, second, populates templates with static site-specific code in order to generate static pages for sites.
+
+***Here are steps of a generation process for site maintainers***:
+
+1. store commonly used, well-tested code in files in selected directories
+2. provide a file describing families of page skeletons
+3. provide a JSON description that selects which skeleton parts are to be used along with source directories
+4. run roll-right in phase 1 with the JSON to generate site templates
+5. provide static components, pictures, etc. to populate templates
+6. run roll-right in phase 2 with .subst files specifying the template population
+7. use other tools to deploy files dropped into a staging directory
+
+The generation process is not limited to coalescing code for pages. There is support for generating node.js modules, generating web page modules, etc. for npm publication.
+
+## install it
+
+```
+npm install -g roll-right
+```
+
+
+## run it
+
+```
+roll-right --phase 1 <website-identifier> <directory including config>
+```
+
+
+
+```
+roll-right --phase 2 <website-identifier> <directory including config>
+```
+
+
+## reverse it
+
+It can help, when developing, to split up a file that has been composed by **roll-right**. Later versions of **roll-right** will put in file separators when files are appended together to form a single file artifact for a web page or module. The command line tool, **roll-right-breakup**, will output a directory of all the files between the separators. There are times that it may be useful to use compare tools with the output of **roll-right-breakup** and the source files.
+
+Here is how to call it:
+
+```
+roll-right-breakup <path to file> <optional output directory>
+```
+
+
+**roll-right-breakup** will create a directory in the calling directory named **rr-breakup** or within the optional directory if it is on the command line.
+
 
 
 ## How it Helps
 
-This is tool is not a replacement for final publication steps enabled by rollup, browserify, or others.
+This tool is not a replacement for final publication steps enabled by rollup, browserify, or others. Instead, this stool may generate code that will be sumbitted to those tools.
 
-This tool provides help with preparing and using an entry point into a module that can be used to obtain the browser version of a module. 
+In fact, whole pages needing no further manipulation may be generated by this tool. So, in some cases this tool does the job that others do. However, some build systems use the other tools to generate their final runtime products. And, this tool may be upstream from those tools.
 
-The aim is make it so that the tool does not have to look at a directory structure of a module, e.g. node_modules in order to get the browser version of some code. It does not require that the code be written in some strange way to accomodate the placement of the same code in two contexts. It does not require reading a special key in a package.json file peculiar to npm.
+In particular, this tool addresses moving preexisting code into certain packaged contexts at the source level. Other packages rollup modules into single code sets or module collections into one file. 
 
-It does require that two versions of the node module/browser module/window level javascript, etc. be available in the package.
+This tool can be used to replicate code into projects, allowing for function by function selection. The final output will be a combined source file with a chain of support for working code. That is, a developer may request that a whole module be copied into a combined source file for a project, or he may select some functions to be placed into the combined source file. But, he may expect that the functions included will have their supporting functions brought in as well.
 
-* It provides tools to help create the separate versions from one. 
-* It provides tools to insert a snippet of code in the interface (entry point) level of the module.
+More commonly, this tool is useful for creating web pages that host bundled operations and that provide basic common libraries that will not be accessed on the global (window) level. In the sense that a browser provides a common library accessible to all parts of a project, a window can offer an extension of that capability. The extension is mostly a packaging of that capability into simpler calls.
 
-The code inserted, is a call that will fetch the browser version of the code and return it to its caller. The caller will usually be the command line version of roll-right. Users will have access to the roll-right command line tool, and will call it to update to the latest browser version of code, depositing it where the rollup (or others) can get at it. 
+One may ask why one would allow code (fixed version) to be copied into a number of projects without creating a module publication. The answer has more to do with expediency of project creation with some time being taken to decide what is a maintable module. The tool will copy just one function from a group of functions into a project if that is specified. But, when the module is maintained, the tool may copy all the function of a group into the new module and ready the code for publication. Projects that use the module will import all the functions in some sense into their code. Certainly, down stream tree shaking may work to reduce the number of functions included. But, that may just move certain worries down stream.
 
-For example, I have a Svelte project that needs some modules, but the modules might not be expressly published in npm. Instead, the modules can be deposited into a common directory accessible by the files in the projects. The build tool will grab those files from that diretory and put them in the final build file.
+So, there are options for deciding how alpha code will be included in projects. But, this tool also provides generation based on skeletons.
 
-For another example, I have some code that must appear at the script level of index.html. It is not intended to be inside a module component. It will just be insterted at some point marked by a variable. The roll-right tool has to call a subtool that does the substitution and leaves the templated result in the appropriate project directory.
+In order to create a template, this tool reads a skeleton file and a JSON configuration that describes how to select alpha code and use some or all of the skeleton to create an .html file that has code and variables, where the mark the place where final code will be placed.
 
 
 ## Setting up publisher calls in a node.js module

package/bin/breakup.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const {FileOperations} = require('extra-file-class')
+
+
+let fosc = new FileOperations(false)
+
+async function process_file(file_name,deposit_dir) {
+    let is_file = await fosc.exists(file_name)
+    if ( is_file ) {
+        if ( await fosc.ensure_directories(deposit_dir) ) {
+            let file_txt = await fosc.load_data_at_path(file_name)
+            if ( file_txt ) {
+                let parts = file_txt.split('// ---->>>')
+                console.log(`# of parts: ${parts.length}`)
+                if ( parts.length > 0 ) {
+                    parts.pop()
+                    let count = 0
+                    let ext = ".html"
+                    for ( let part of parts ) {
+                        count++
+                        await fosc.output_string(`${deposit_dir}/part_${count}.${ext}`,parts[count-1])
+                        ext = "js"
+                    }
+                }
+            } else {
+                console.log(`Could not read ${file_name}`)
+            }
+        }
+    } else {
+        console.log(`can't find file ${file_name}`)
+    }
+}
+
+
+let deposit_dir = "rr-breakup"
+let holding_dir = process.argv[3]
+if ( holding_dir !== undefined  ) {
+    if ( holding_dir[holding_dir.length-1] !== '/' ) {
+        holding_dir += '/'
+    }
+    deposit_dir = holding_dir + deposit_dir
+}
+
+
+let file = process.argv[2]
+//
+if ( file === undefined ) {
+    console.log("roll-right-breakup is expecting at least one command line parameter: name of file to be processed")
+} else {
+    console.log(file)
+    process_file(file,deposit_dir)    
+}
+
+

package/bin/index.js

@@ -1,14 +1,117 @@
 #!/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 papa = require('../index.js')
+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 = "."
+}
 
-console.log(__filename)
-console.log(process.argv[0])
-console.log(process.argv[1])
 
+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;
+                    }
+
+                }
+            }
+        }
+    } 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
+                }
+                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 
+                }
+                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 = 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)
+    }
+
+}
+
+
+
+command_line_operations()

package/index.js

@@ -7,5 +7,5 @@ module.exports.browser_code = roll_right_utilities.browser_code_access
 
 
 module.exports.identify_me = () => {
-    console.log("I AM ROLL-RIGHT")
+    console.log("roll-right static content management and module publication")
 }

package/lib/mod_utils.js

@@ -0,0 +1,79 @@
+
+const fs = require('fs')
+const path = require('path')
+const {load_json_file,array_flatten} = require('../lib/utils')
+const {execSync} = require('child_process')
+const {translate_marker} = require('../lib/utils')
+
+
+
+async function cp_module_to(dest,src,config) {
+    let src_dr = translate_marker(src,config)
+    let dest_file = translate_marker(dest,config)
+    //
+    let path_parts = dest_file.split('/')
+    try {
+        let src_file = `${src_dr}/${path_parts[path_parts.length-1]}`
+        fs.copyFileSync(src_file,dest_file)
+    } catch (e) {
+        console.log(e)
+    }
+    //
+}
+
+async function check_tests(src,dest,config) {
+    return true
+}
+
+async function shell_command(cmd) {
+    try {
+        execSync(cmd,{
+            stdio: [0, 1, 2]
+        })
+    } catch (e) {
+        console.log(e)
+    }
+}
+
+
+function bump_npm_version() {
+    let npm = load_json_file("package.json")
+    let v = npm.version
+    let semv = v.split('.')
+    let minv = parseInt(semv[semv.length - 1])
+    minv++
+    semv[semv.length - 1] = "" + minv
+    npm.version = semv.join('.')
+    fs.writeFileSync("package.json",JSON.stringify(npm,null,2))
+}
+
+
+async function npm_publish() {
+    await shell_command("npm publish .")
+}
+
+async function port_modules(config,flags) {
+    //
+    let all_tests = true
+    for ( let mod in config.sources ) {
+        let tests_ok = await check_tests(mod,config.sources[mod],config)
+        if ( tests_ok ) {
+            await cp_module_to(mod,config.sources[mod],config)
+        }
+        all_tests = all_tests && tests_ok
+    }
+    //
+    if ( all_tests ) {
+        switch ( config.mod_type ) {
+            case "npm" :
+            default: {
+                if ( flags.publish ) {
+                    bump_npm_version()
+                    await npm_publish()    
+                }
+            }
+        }    
+    }
+}
+
+module.exports.port_modules = port_modules