quackage 1.0.47 → 1.0.50

package/docs/README.md

@@ -0,0 +1,111 @@
+# Quackage
+
+> Building. Testing. Quacking. Reloading.
+
+Quackage is a CLI toolkit for managing, building, testing and documenting JavaScript/Node.js modules. It wraps common tools (Gulp, Mocha, Babel, Browserify, JSDoc, Indoctrinate, pict-docuserve) behind a consistent command interface and manages `package.json` configuration so every module in your ecosystem follows the same conventions.
+
+Quackage exists because maintaining dozens of modules by hand is tedious and error-prone. Instead of copy-pasting npm scripts, Babel configs and Gulp tasks between projects, quackage keeps a single canonical set of defaults and applies them everywhere. When conventions change, one `quack updatepackage` brings every module up to date.
+
+## Installation
+
+```bash
+npm install quackage
+```
+
+Or install globally:
+
+```bash
+npm install -g quackage
+```
+
+## Usage
+
+Quackage provides two equivalent CLI entry points:
+
+```bash
+quack <command> [options]
+qua <command> [options]
+```
+
+Run `quack --help` to see all available commands, or `quack <command> --help` for details on a specific command.
+
+## Command Reference
+
+Commands are organized into five categories:
+
+### [Package Management](commands/package-management/README.md)
+
+Commands for keeping your `package.json` in sync with quackage conventions.
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `updatepackage` | `update_package` | Add standard test, build and coverage scripts |
+| `luxuryupdatepackage` | `luxury_update_package`, `lux` | Add Docker-based luxury dev environment scripts |
+| `lint` | | Audit your package.json against quackage defaults |
+
+### [Boilerplate](commands/boilerplate/README.md)
+
+Commands for generating and managing file templates.
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `boilerplate` | `boil`, `bp` | Generate files from a template fileset |
+| `listtemplates` | `list`, `ls`, `lt` | Show available template filesets |
+| `buildtemplates` | `bt` | Create template filesets from a folder |
+
+### [Compiling](commands/compiling/README.md)
+
+Commands for compiling schemas and assembling view configurations.
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `stricture-compile` | `scomp` | Compile Stricture DDL into a Meadow schema |
+| `stricture-legaacy` | `str` | Run a legacy Stricture command |
+| `assemble_json_views` | `ajv` | Assemble Pict JSON view configurations from HTML |
+
+### [Building](commands/building/README.md)
+
+Commands for building, copying and testing your module.
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `build` | | Browserify and minify your module into `dist/` |
+| `copy-files-from-to` | `copy`, `cp` | Copy files to a staging location |
+| `run-mocha-tests` | `test` | Run Mocha tests in TDD mode |
+
+### [Documentation](commands/documentation/README.md)
+
+Commands for generating and serving documentation.
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `generate-documentation` | `dgen` | Generate JSDoc documentation from source |
+| `indoctrinate` | `indoc` | Generate a module documentation catalog |
+| `indoctrinate-index` | `indoc-index`, `keyword-index` | Generate a keyword search index |
+| `docuserve-inject` | `docuserve`, `inject-docs` | Inject pict-docuserve assets for static hosting |
+| `prepare-docs` | `docs`, `prep-docs` | All-in-one documentation preparation |
+| `prepare-local` | `local-docs`, `stage-local` | Copy local JS bundles for offline use |
+| `docs-serve` | `serve-docs` | Serve documentation locally |
+
+## Configuration
+
+Quackage looks for a `.quackage.json` file in your project root for custom configuration. If none is found it uses sensible defaults defined in `Default-Quackage-Configuration.json`.
+
+Key configuration sections:
+
+- `GulpExecutions` -- Build targets (default and compatible)
+- `GulpfileConfiguration` -- Entry point, output folder, file naming
+- `DefaultBabelRC` -- Babel preset and source map settings
+- `PackageScripts` -- Standard npm scripts quackage manages
+- `LuxuryPackageScripts` -- Docker dev environment scripts
+- `WatchSettings` -- Folders and commands for file watching
+
+## Executable Resolution
+
+Quackage resolves tool binaries (gulp, mocha, indoctrinate, pict-docuserve, copy-files-from-to) by searching three locations in order:
+
+1. `{CWD}/node_modules/.bin/` -- your project's local install
+2. `{quackage}/../.bin/` -- relative to the quackage package
+3. `{quackage}/node_modules/.bin/` -- quackage's own dependencies
+
+This means quackage works whether installed locally, globally or from a monorepo root.

package/docs/_sidebar.md

@@ -0,0 +1,35 @@
+- [Quackage](README.md)
+
+- Package Management
+  - [Overview](commands/package-management/README.md)
+  - [updatepackage](commands/package-management/updatepackage.md)
+  - [luxuryupdatepackage](commands/package-management/luxuryupdatepackage.md)
+  - [lint](commands/package-management/lint.md)
+
+- Boilerplate
+  - [Overview](commands/boilerplate/README.md)
+  - [boilerplate](commands/boilerplate/boilerplate.md)
+  - [listtemplates](commands/boilerplate/listtemplates.md)
+  - [buildtemplates](commands/boilerplate/buildtemplates.md)
+
+- Compiling
+  - [Overview](commands/compiling/README.md)
+  - [stricture-compile](commands/compiling/stricture-compile.md)
+  - [stricture-legaacy](commands/compiling/stricture-legaacy.md)
+  - [assemble_json_views](commands/compiling/assemble_json_views.md)
+
+- Building
+  - [Overview](commands/building/README.md)
+  - [build](commands/building/build.md)
+  - [copy-files-from-to](commands/building/copy-files-from-to.md)
+  - [run-mocha-tests](commands/building/run-mocha-tests.md)
+
+- Documentation
+  - [Overview](commands/documentation/README.md)
+  - [generate-documentation](commands/documentation/generate-documentation.md)
+  - [indoctrinate](commands/documentation/indoctrinate.md)
+  - [indoctrinate-index](commands/documentation/indoctrinate-index.md)
+  - [docuserve-inject](commands/documentation/docuserve-inject.md)
+  - [prepare-docs](commands/documentation/prepare-docs.md)
+  - [prepare-local](commands/documentation/prepare-local.md)
+  - [docs-serve](commands/documentation/docs-serve.md)

package/docs/_topbar.md

@@ -0,0 +1,5 @@
+# Quackage
+- [Docs](/)
+- [Commands](commands/building/README.md)
+- [GitHub](https://github.com/stevenvelozo/quackage)
+- [npm](https://www.npmjs.com/package/quackage)

package/docs/commands/boilerplate/README.md

@@ -0,0 +1,45 @@
+# Boilerplate
+
+Commands for generating and managing file templates. Quackage uses a JSON-based template system that lets you scaffold common file structures from reusable filesets.
+
+## Commands
+
+- [boilerplate](boilerplate.md) -- Generate files from a template fileset
+- [listtemplates](listtemplates.md) -- Show available template filesets
+- [buildtemplates](buildtemplates.md) -- Create template filesets from a folder
+
+## Overview
+
+Template filesets are stored in `.quackage-templates.json` files. Quackage merges templates from three sources (in order):
+
+1. Built-in -- shipped with the quackage package
+2. Project -- `.quackage-templates.json` in your current working directory
+3. Home -- `~/.quackage-templates.json` in your home directory
+
+Later sources override earlier ones, so you can customize built-in templates at the project or user level.
+
+## Template File Format
+
+A `.quackage-templates.json` file is a JSON object where each key is a fileset name:
+
+```json
+{
+  "my-fileset": {
+    "Hash": "MyFileset",
+    "Name": "My Fileset",
+    "Description": "Creates a standard module scaffold.",
+    "Files": [
+      {
+        "Hash": "IndexJs",
+        "Path": "source/index.js",
+        "Content": "module.exports = {};\n"
+      }
+    ],
+    "Templates": {
+      "CustomHelper": "some reusable template content"
+    }
+  }
+}
+```
+
+File paths and content support the Pict template engine, so you can use expressions like `{~Data:Scope~}` to inject the scope name or other context.

package/docs/commands/boilerplate/boilerplate.md

@@ -0,0 +1,55 @@
+# boilerplate
+
+Generate files from a named template fileset.
+
+## Usage
+
+```bash
+quack boilerplate <fileset> [options]
+```
+
+Aliases: `boil`, `bp`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `fileset` | The name of the template fileset to generate (required) |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-s, --scope <scope>` | `Default` | A scope identifier passed into templates as a variable |
+| `-f, --force` | | Force overwrite existing files |
+
+## Behavior
+
+1. Loads template filesets from all three sources (built-in, project `.quackage-templates.json`, home `~/.quackage-templates.json`) and merges them
+2. Looks up the requested fileset by name
+3. For each file in the fileset:
+   - Resolves the file path through the Pict template engine (paths can contain template expressions)
+   - Creates any necessary parent directories
+   - If the file already exists and `--force` is not set: warns and suggests backup/delete commands
+   - If the file does not exist (or `--force` is set): renders the content through the template engine and writes it
+4. Templates have access to the scope, package.json data, and quackage configuration
+
+## Template Variables
+
+Templates can reference:
+
+- `{~Data:Scope~}` -- the `--scope` value
+- `{~Data:FileSetName~}` -- the fileset key
+- Package.json data through `AppData.Package`
+- `QUACKAGEPROJECTNAMECAP` -- the capitalized project name
+- `QUACKAGESCOPE` -- the scope value (in file paths)
+
+## Example
+
+```bash
+# Generate a unit test boilerplate scoped to "User"
+quack boilerplate unit-test --scope User
+
+# Overwrite existing files
+quack bp unit-test --scope User --force
+```

package/docs/commands/boilerplate/buildtemplates.md

@@ -0,0 +1,47 @@
+# buildtemplates
+
+Create template filesets from the contents of a folder. Each top-level subfolder becomes its own template fileset.
+
+## Usage
+
+```bash
+quack buildtemplates <folder>
+```
+
+Aliases: `bt`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `folder` | The folder path to scan for template content (required) |
+
+## Behavior
+
+1. Reads the target folder
+2. Each top-level subdirectory becomes a named template fileset (the folder name is cleaned to alphanumeric characters)
+3. Files within each subdirectory are read recursively and added to that fileset with their relative paths preserved
+4. Top-level files (not in a subdirectory) become their own single-file filesets
+5. If a `.quackage-templates.json` already exists in the working directory, the new filesets are merged into it
+6. Writes the result to `.quackage-templates.json`
+
+## Example
+
+Given this folder structure:
+
+```
+templates/
+  unit-test/
+    test/test.js
+    test/test-helper.js
+  service/
+    source/MyService.js
+```
+
+Running:
+
+```bash
+quack bt templates
+```
+
+Produces a `.quackage-templates.json` with two filesets: `unittest` and `service`, each containing the respective files with their content and relative paths.

package/docs/commands/boilerplate/listtemplates.md

@@ -0,0 +1,38 @@
+# listtemplates
+
+List all available boilerplate template filesets.
+
+## Usage
+
+```bash
+quack listtemplates
+```
+
+Aliases: `list`, `ls`, `lt`
+
+## Behavior
+
+1. Loads the built-in template filesets from quackage
+2. Merges in any project-level templates from `{CWD}/.quackage-templates.json`
+3. Merges in any user-level templates from `~/.quackage-templates.json`
+4. Prints each fileset name and the number of templated files it contains
+
+## Example
+
+```bash
+quack ls
+```
+
+Output:
+
+```
+unit-test ______________________________ (2 templated files)
+pict-view ______________________________ (4 templated files)
+service ________________________________ (3 templated files)
+```
+
+Use the fileset name with the `boilerplate` command to generate files:
+
+```bash
+quack bp unit-test
+```

package/docs/commands/building/README.md

@@ -0,0 +1,28 @@
+# Building
+
+Commands for building, copying and testing your module. These are the core development workflow commands you'll use most frequently.
+
+## Commands
+
+- [build](build.md) -- Browserify and minify your module into `dist/`
+- [copy-files-from-to](copy-files-from-to.md) -- Copy files to a staging location
+- [run-mocha-tests](run-mocha-tests.md) -- Run Mocha tests in TDD mode
+
+## Typical Workflow
+
+```bash
+# Run tests
+quack test
+
+# Build for distribution
+quack build
+
+# Copy static assets to staging
+quack copy
+```
+
+The standard `npm run build` script added by `quack updatepackage` runs `npx quack build`. For pict applications, the typical build sequence is:
+
+```bash
+npx quack build && npx quack copy
+```

package/docs/commands/building/build.md

@@ -0,0 +1,77 @@
+# build
+
+Browserify and minify your module into a `dist/` folder using Gulp.
+
+## Usage
+
+```bash
+quack build
+```
+
+## Behavior
+
+The build command runs one or more Gulp-based build targets. By default, quackage defines two build executions:
+
+### Build Targets
+
+| Target | File Label | Browsers List | Output |
+|--------|-----------|---------------|--------|
+| Default | *(none)* | `since 2018` | `{name}.js` / `{name}.min.js` |
+| Compatible | `compatible.` | `> 0.01%` | `{name}.compatible.js` / `{name}.compatible.min.js` |
+
+### Build Steps (per target)
+
+For each build target, the command:
+
+1. Writes `.browserslistrc` -- sets the Browserslist query for this target. Backs up any existing file to `.browserslistrc-BACKUP`
+2. Writes `.babelrc` -- creates a Babel config with `@babel/preset-env` and source maps (only if `.babelrc` doesn't already exist)
+3. Writes `.gulpfile-quackage-config.json` -- the Gulp configuration with entry point, output folder and file names, resolved from your `package.json` `main` field
+4. Writes `.gulpfile-quackage.js` -- the Gulp entry point that requires the quackage gulpfile
+5. Runs Gulp -- executes the build using the generated gulpfile
+
+### Build Configuration
+
+The build reads configuration from `.quackage.json` (or the defaults). Key fields:
+
+```json
+{
+  "GulpfileConfiguration": {
+    "EntrypointInputSourceFile": "{CWD}/{package.main}",
+    "LibraryObjectName": "{PascalCaseName}",
+    "LibraryOutputFolder": "{CWD}/dist/",
+    "LibraryUniminifiedFileName": "{name}.js",
+    "LibraryMinifiedFileName": "{name}.min.js"
+  }
+}
+```
+
+## Customization
+
+To customize build targets, create a `.quackage.json` in your project root and override the `GulpExecutions` array:
+
+```json
+{
+  "GulpExecutions": [
+    {
+      "Hash": "modern",
+      "Name": "Modern browsers only",
+      "BuildFileLabel": "",
+      "BrowsersListRC": "last 2 versions"
+    }
+  ]
+}
+```
+
+## Example
+
+```bash
+quack build
+```
+
+Output:
+
+```
+###############################[ BUILDING Default standard build. ]###############################
+Quackage found gulp at ./node_modules/.bin/gulp ... executing build from there.
+###############################[ BUILDING Default standard build. ]###############################
+```

package/docs/commands/building/copy-files-from-to.md

@@ -0,0 +1,34 @@
+# copy-files-from-to
+
+Copy files to a staging location using the `copy-files-from-to` utility.
+
+## Usage
+
+```bash
+quack copy-files-from-to
+```
+
+Aliases: `copy`, `cp`
+
+## Behavior
+
+Executes the `copy-files-from-to` npm package, which reads its own configuration from `copyFiles.json` or `copyFilesSettings` in your `package.json`. Quackage simply locates and runs the binary -- the copy rules themselves are defined in your project.
+
+See the [copy-files-from-to documentation](https://github.com/nicedreams/copy-files-from-to) for configuration details.
+
+## Common Use
+
+This command is typically run after `build` to copy static assets (HTML, CSS, images) alongside the compiled JavaScript:
+
+```bash
+quack build && quack copy
+```
+
+The `WatchSettings` in the quackage default configuration monitors `./html`, `./css` and `./assets` folders and runs `npx quack copy` when files change.
+
+## Example
+
+```bash
+# Copy files according to your copyFiles configuration
+quack cp
+```

package/docs/commands/building/run-mocha-tests.md

@@ -0,0 +1,43 @@
+# run-mocha-tests
+
+Run Mocha tests in TDD mode with the spec reporter.
+
+## Usage
+
+```bash
+quack run-mocha-tests [options]
+```
+
+Aliases: `test`
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-g, --grep <expression>` | A grep search expression to filter which tests run |
+
+## Behavior
+
+1. Locates the Mocha binary using the standard executable resolution order (CWD, quackage package, git repo)
+2. Runs Mocha with:
+   - `-u tdd` -- TDD interface (suite/test)
+   - `-R spec` -- spec reporter
+   - `--exit` -- (only when using `--grep`) force exit after tests complete
+3. If `--grep` is provided, only tests matching the expression are executed
+
+## Example
+
+```bash
+# Run all tests
+quack test
+
+# Run only tests matching "User"
+quack test --grep User
+```
+
+This is equivalent to the standard npm script added by `updatepackage`:
+
+```bash
+npm test
+# runs: npx mocha -u tdd -R spec
+```

package/docs/commands/compiling/README.md

@@ -0,0 +1,21 @@
+# Compiling
+
+Commands for compiling schema definitions and assembling view configurations. These commands transform source artifacts into JSON structures consumed by the Meadow ORM and Pict view system.
+
+## Commands
+
+- [stricture-compile](stricture-compile.md) -- Compile Stricture DDL into a Meadow schema
+- [stricture-legaacy](stricture-legaacy.md) -- Run a legacy Stricture command
+- [assemble_json_views](assemble_json_views.md) -- Assemble Pict JSON view configurations from HTML/template files
+
+## Overview
+
+### Stricture
+
+Stricture is the schema definition language for Meadow (the Retold ORM layer). The `stricture-compile` and `stricture-legaacy` commands provide quackage integration points for compiling Stricture DDL files into the JSON schema format Meadow expects.
+
+> Note: Both Stricture commands are currently placeholder stubs awaiting full implementation. They accept arguments and options but do not yet perform compilation.
+
+### Pict View Assembly
+
+The `assemble_json_views` command scans a folder of HTML or template files and generates the JSON view configuration objects that the Pict view system expects. This eliminates the need to hand-write view JSON for simple template-based views.

package/docs/commands/compiling/assemble_json_views.md

@@ -0,0 +1,74 @@
+# assemble_json_views
+
+Assemble Pict JSON view configurations from a folder of HTML or template files.
+
+## Usage
+
+```bash
+quack assemble_json_views <folder> [options]
+```
+
+Aliases: `ajv`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `folder` | The folder path to scan for view template files (required) |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-p, --prefix <prefix>` | `Default` | A prefix for the generated view set identifiers |
+
+## Behavior
+
+1. Resolves the folder path relative to the current working directory
+2. Recursively scans all files in the folder (and subfolders)
+3. For each file, generates a Pict view JSON object containing:
+   - `ViewIdentifier` -- `{Prefix}-{CleanFileName}-View`
+   - `DefaultRenderable` -- `{Prefix}-{CleanFileName}-Renderable`
+   - `DefaultDestinationAddress` -- `#{Prefix}-Content-Container`
+   - `Templates` -- array with one entry containing the file content as the template
+   - `Renderables` -- array linking the renderable hash to the template hash
+   - `AutoRender` -- set to `false`
+4. Writes the complete view set to `{Prefix}-View-Templates.json` in the working directory
+
+## Output Format
+
+Each generated view follows this structure:
+
+```json
+{
+  "Prefix-FileName-View": {
+    "ViewIdentifier": "Prefix-FileName-View",
+    "DefaultRenderable": "Prefix-FileName-Renderable",
+    "DefaultDestinationAddress": "#Prefix-Content-Container",
+    "AutoRender": false,
+    "Templates": [
+      {
+        "Hash": "Prefix-FileName-Content-Template",
+        "Template": "...file contents..."
+      }
+    ],
+    "Renderables": [
+      {
+        "RenderableHash": "Prefix-FileName-Renderable",
+        "TemplateHash": "Prefix-FileName-Content-Template"
+      }
+    ]
+  }
+}
+```
+
+## Example
+
+```bash
+# Scan ./views and generate Default-View-Templates.json
+quack ajv ./views
+
+# Use a custom prefix
+quack ajv ./views --prefix MyApp
+# Produces MyApp-View-Templates.json
+```

package/docs/commands/compiling/stricture-compile.md

@@ -0,0 +1,33 @@
+# stricture-compile
+
+Compile Stricture DDL into a Meadow schema file.
+
+## Usage
+
+```bash
+quack stricture-compile <output_folder> [options]
+```
+
+Aliases: `scomp`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `output_folder` | The folder in which to generate the compiled schema (required) |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-m, --markdown <folder>` | | Folder with markdown documentation; subfolders are okay |
+
+## Status
+
+> Stub: This command is currently a placeholder. It accepts arguments and options but does not yet perform compilation. The implementation will compile Stricture DDL definitions into the JSON schema format consumed by Meadow.
+
+## Example
+
+```bash
+quack scomp ./schema
+```