quackage 1.0.46 → 1.0.48

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

@@ -0,0 +1,33 @@
+# stricture-legaacy
+
+Run a legacy Stricture command.
+
+## Usage
+
+```bash
+quack stricture-legaacy <output_folder> [options]
+```
+
+Aliases: `str`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `output_folder` | The folder in which to generate content (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 any processing. It is intended to provide backward compatibility with older Stricture workflows.
+
+## Example
+
+```bash
+quack str ./output
+```

package/docs/commands/documentation/README.md

@@ -0,0 +1,41 @@
+# Documentation
+
+Commands for generating and serving documentation. Quackage integrates three documentation tools:
+
+- JSDoc -- extracts API documentation from source code comments
+- Indoctrinate -- scans a module tree and generates a documentation catalog with cross-module navigation and keyword search
+- pict-docuserve -- provides a web application shell (based on Docsify) for browsing documentation, either as injected static assets or via a local dev server
+
+## Commands
+
+- [generate-documentation](generate-documentation.md) -- Generate JSDoc documentation from source
+- [indoctrinate](indoctrinate.md) -- Generate a module documentation catalog
+- [indoctrinate-index](indoctrinate-index.md) -- Generate a keyword search index
+- [docuserve-inject](docuserve-inject.md) -- Inject pict-docuserve assets for static hosting
+- [prepare-docs](prepare-docs.md) -- All-in-one documentation preparation
+- [prepare-local](prepare-local.md) -- Copy local JS bundles for offline use
+- [docs-serve](docs-serve.md) -- Serve documentation locally
+
+## Quick Start
+
+For most projects, the all-in-one `prepare-docs` command is all you need:
+
+```bash
+# Prepare documentation (catalog + search index + web assets)
+quack prepare-docs ./docs -d ./modules
+
+# Serve it locally
+quack docs-serve ./docs
+```
+
+Both commands default to `./docs` if no folder argument is provided.
+
+## Documentation Pipeline
+
+The `prepare-docs` command runs these three steps in sequence:
+
+1. Indoctrinate catalog -- scans the module directory tree and generates `retold-catalog.json`
+2. Keyword index -- generates `retold-keyword-index.json` for search
+3. Docuserve inject -- copies the pict-docuserve web application assets and writes a `.nojekyll` file for GitHub Pages
+
+You can also run each step individually for finer control.

package/docs/commands/documentation/docs-serve.md

@@ -0,0 +1,54 @@
+# docs-serve
+
+Serve a documentation folder locally using pict-docuserve.
+
+## Usage
+
+```bash
+quack docs-serve [docs_folder] [options]
+```
+
+Aliases: `serve-docs`
+
+## Arguments
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `docs_folder` | `./docs` | The documentation folder to serve |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-p, --port <port>` | `3333` | Port to serve on |
+
+## Behavior
+
+1. Resolves the docs folder path (defaults to `./docs` if not provided)
+2. Validates the folder exists
+3. Locates the `pict-docuserve` binary
+4. Runs `pict-docuserve serve` to start a local HTTP server
+
+The server runs in the foreground until you stop it with Ctrl+C.
+
+## Example
+
+```bash
+# Serve ./docs on the default port (3333)
+quack docs-serve
+
+# Serve on a custom port
+quack serve-docs ./docs --port 8080
+
+# Prepare and serve in one line
+quack prepare-docs && quack docs-serve
+```
+
+Then open `http://localhost:3333` in your browser.
+
+This is equivalent to the standard npm script added by `updatepackage`:
+
+```bash
+npm run docs-serve
+# runs: npx quack docs-serve ./docs
+```

package/docs/commands/documentation/docuserve-inject.md

@@ -0,0 +1,46 @@
+# docuserve-inject
+
+Inject pict-docuserve web application assets into a documentation folder for static hosting.
+
+## Usage
+
+```bash
+quack docuserve-inject <docs_folder>
+```
+
+Aliases: `docuserve`, `inject-docs`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `docs_folder` | Target documentation folder to inject assets into (required) |
+
+## Behavior
+
+1. Resolves the docs folder path, creating it if necessary
+2. Locates the `pict-docuserve` binary
+3. Runs `pict-docuserve inject` to copy the web application shell into the target folder
+4. Writes an empty `.nojekyll` file for GitHub Pages compatibility (prevents Jekyll processing)
+
+## What Gets Injected
+
+The inject command copies a lightweight set of files into your docs folder:
+
+- `index.html` -- the documentation shell (loads JS dependencies from jsDelivr CDN)
+- `css/` -- stylesheet assets for the viewer
+- `.nojekyll` -- prevents GitHub Pages from processing files with Jekyll
+
+JavaScript dependencies (`pict` and `pict-docuserve`) are loaded from the jsDelivr CDN by default, keeping the injected footprint small. For offline or local development, use `prepare-local` to copy local JS bundles instead.
+
+After injection, the folder can be served as a static site (e.g. via GitHub Pages) or locally with `docs-serve`.
+
+## Example
+
+```bash
+# Inject into ./docs
+quack inject-docs ./docs
+
+# Then serve locally to preview
+quack docs-serve ./docs
+```

package/docs/commands/documentation/generate-documentation.md

@@ -0,0 +1,47 @@
+# generate-documentation
+
+Generate JSDoc documentation from source files.
+
+## Usage
+
+```bash
+quack generate-documentation <output_folder> [options]
+```
+
+Aliases: `dgen`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `output_folder` | The folder in which to generate documentation output (required) |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-m, --markdown <folder>` | | Folder with markdown documentation; subfolders are okay |
+| `-s, --source <folder>` | | Folder with JavaScript source to parse JSDoc from |
+| `-c, --config <file>` | | Path to a JSDoc config file |
+
+## Behavior
+
+1. Resolves the output folder path, creating it if necessary
+2. If `--source` is provided, runs JSDoc with the `-X` flag to produce raw JSON output
+3. JSDoc is resolved from your project's `node_modules` first; falls back to `npx jsdoc` if not found locally
+4. Writes the raw JSDoc JSON to `JSDocOutput.json` in the output folder
+5. Supports a 60-second timeout for JSDoc execution
+
+## Output
+
+The primary output is `JSDocOutput.json` -- the raw JSON doclet array produced by `jsdoc -X`. This can be consumed by other tools for further processing.
+
+## Example
+
+```bash
+# Generate docs from source/ into docs/api/
+quack dgen ./docs/api --source ./source
+
+# With a custom JSDoc config
+quack dgen ./docs/api --source ./source --config ./jsdoc.conf.json
+```

package/docs/commands/documentation/indoctrinate-index.md

@@ -0,0 +1,41 @@
+# indoctrinate-index
+
+Generate a Lunr keyword search index from module documentation using Indoctrinate.
+
+## Usage
+
+```bash
+quack indoctrinate-index <docs_folder> [options]
+```
+
+Aliases: `indoc-index`, `keyword-index`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `docs_folder` | The documentation output folder for the generated keyword index (required) |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-d, --directory_root <path>` | CWD | Root directory to scan for modules |
+
+## Behavior
+
+1. Resolves the docs folder path, creating it if necessary
+2. Locates the `indoctrinate` binary
+3. Runs `indoctrinate generate_keyword_index` with the directory root and output file
+4. Writes `retold-keyword-index.json` to the docs folder
+
+## Output
+
+The keyword index (`retold-keyword-index.json`) is a pre-built Lunr search index that enables client-side full-text search across all module documentation. It is consumed by the pict-docuserve web application's search feature.
+
+## Example
+
+```bash
+# Generate keyword index from ./modules into ./docs
+quack keyword-index ./docs -d ./modules
+```

package/docs/commands/documentation/indoctrinate.md

@@ -0,0 +1,46 @@
+# indoctrinate
+
+Generate a documentation catalog from module documentation folders using the Indoctrinate tool.
+
+## Usage
+
+```bash
+quack indoctrinate <docs_folder> [options]
+```
+
+Aliases: `indoc`
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `docs_folder` | The documentation output folder for the generated catalog (required) |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-d, --directory_root <path>` | CWD | Root directory to scan for modules |
+| `-b, --branch <branch>` | `master` | Git branch for GitHub raw URLs |
+| `-g, --github_org <org>` | `stevenvelozo` | GitHub organization for raw URLs |
+
+## Behavior
+
+1. Resolves the docs folder path, creating it if necessary
+2. Locates the `indoctrinate` binary
+3. Runs `indoctrinate generate_catalog` with the directory root, output file, branch and GitHub org parameters
+4. Writes `retold-catalog.json` to the docs folder
+
+## Output
+
+The catalog file (`retold-catalog.json`) contains a structured listing of all modules found under the directory root, including their documentation paths and GitHub raw content URLs. This is consumed by the pict-docuserve web application for cross-module navigation.
+
+## Example
+
+```bash
+# Generate catalog from ./modules into ./docs
+quack indoc ./docs -d ./modules
+
+# Different branch and org
+quack indoc ./docs -d ./modules -b develop -g myorg
+```

package/docs/commands/documentation/prepare-docs.md

@@ -0,0 +1,65 @@
+# prepare-docs
+
+All-in-one documentation preparation. Generates the catalog, builds the keyword search index and injects pict-docuserve assets in a single command.
+
+## Usage
+
+```bash
+quack prepare-docs [docs_folder] [options]
+```
+
+Aliases: `docs`, `prep-docs`
+
+## Arguments
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `docs_folder` | `./docs` | The documentation folder to prepare |
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-d, --directory_root <path>` | CWD | Root directory to scan for modules |
+| `-b, --branch <branch>` | `master` | Git branch for GitHub raw URLs |
+| `-g, --github_org <org>` | `stevenvelozo` | GitHub organization for raw URLs |
+
+## Behavior
+
+Runs three steps in sequence:
+
+### Step 1: Indoctrinate Catalog
+
+Runs `indoctrinate generate_catalog` to scan the module directory tree and produce `retold-catalog.json` in the docs folder.
+
+### Step 2: Keyword Index
+
+Runs `indoctrinate generate_keyword_index` to produce `retold-keyword-index.json` in the docs folder.
+
+### Step 3: Docuserve Inject
+
+Runs `pict-docuserve inject` to copy the web application assets into the docs folder.
+
+### Final
+
+Writes a `.nojekyll` file for GitHub Pages compatibility.
+
+## Example
+
+```bash
+# Prepare docs with defaults (./docs folder, scan CWD)
+quack prepare-docs
+
+# Specify folder and module root
+quack prepare-docs ./docs -d ./modules
+
+# Use a different branch and org
+quack docs ./docs -d ./modules -b develop -g myorg
+```
+
+This is equivalent to the standard npm script added by `updatepackage`:
+
+```bash
+npm run docs
+# runs: npx quack prepare-docs ./docs -d ./modules
+```

package/docs/commands/documentation/prepare-local.md

@@ -0,0 +1,49 @@
+# prepare-local
+
+Copy local JavaScript bundles into a documentation folder for offline use. Rewrites `index.html` to reference the local files instead of the jsDelivr CDN.
+
+## Usage
+
+```bash
+quack prepare-local [docs_folder]
+```
+
+Aliases: `local-docs`, `stage-local`
+
+## Arguments
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `docs_folder` | `./docs` | The documentation folder to prepare for offline use |
+
+## Behavior
+
+1. Resolves the docs folder path (defaults to `./docs` if not provided)
+2. Locates the `pict-docuserve` binary
+3. Runs `pict-docuserve prepare-local` which:
+   - Copies `pict.min.js` and its source map from the pict-docuserve dist folder into a `js/` subfolder
+   - Copies `pict-docuserve.min.js` and its source map into the docs folder root
+   - Rewrites `index.html` to load JavaScript from local paths instead of jsDelivr CDN
+
+## When to Use
+
+By default, `docuserve-inject` and `prepare-docs` produce an `index.html` that loads `pict` and `pict-docuserve` from the jsDelivr CDN. This keeps the injected footprint small and ensures you always get the latest compatible version.
+
+Use `prepare-local` when you need:
+
+- Offline documentation browsing (no internet required)
+- A fully self-contained docs folder for air-gapped environments
+- Pinned JS versions that do not change between deploys
+
+## Example
+
+```bash
+# Prepare docs normally (CDN mode)
+quack prepare-docs ./docs -d ./modules
+
+# Then copy local JS bundles for offline use
+quack prepare-local ./docs
+
+# Serve locally
+quack docs-serve ./docs
+```

package/docs/commands/package-management/README.md

@@ -0,0 +1,39 @@
+# Package Management
+
+Commands for keeping your `package.json` in sync with quackage conventions. These commands ensure every module in your ecosystem has consistent test, build, coverage and Docker scripts.
+
+## Commands
+
+- [updatepackage](updatepackage.md) -- Add standard scripts and configuration sections
+- [luxuryupdatepackage](luxuryupdatepackage.md) -- Add Docker-based luxury dev environment scripts
+- [lint](lint.md) -- Audit your package.json against quackage defaults
+
+## Overview
+
+Quackage defines a canonical set of `package.json` sections and npm scripts. The `updatepackage` command adds any missing entries, while `lint` reports on what matches and what doesn't -- without modifying anything.
+
+Both `updatepackage` and `luxuryupdatepackage` create a backup at `.package.json.quackage.bak` before writing changes.
+
+### Standard Scripts
+
+The following scripts are managed by `updatepackage`:
+
+| Script | Command |
+|--------|---------|
+| `start` | `node {main}` |
+| `test` | `npx mocha -u tdd -R spec` |
+| `tests` | `npx mocha -u tdd --exit -R spec --grep` |
+| `coverage` | `npx nyc --reporter=lcov --reporter=text-lcov npx mocha -- -u tdd -R spec` |
+| `build` | `npx quack build` |
+| `docs` | `npx quack prepare-docs ./docs -d ./modules` |
+| `docs-serve` | `npx quack docs-serve ./docs` |
+
+### Luxury Scripts
+
+The following scripts are managed by `luxuryupdatepackage`:
+
+| Script | Command |
+|--------|---------|
+| `docker-dev-build` | `docker build ./ -f Dockerfile_LUXURYCode -t {name}-image:local` |
+| `docker-dev-run` | `docker run -it -d --name {name}-dev ...` |
+| `docker-dev-shell` | `docker exec -it {name}-dev /bin/bash` |

package/docs/commands/package-management/lint.md

@@ -0,0 +1,36 @@
+# lint
+
+Audit your `package.json` against quackage's default configuration without modifying anything.
+
+## Usage
+
+```bash
+quack lint
+```
+
+## Behavior
+
+Performs a read-only comparison of your `package.json` against the quackage defaults:
+
+1. Checks each quackage-managed section (e.g. `mocha`) for existence and value match
+2. Checks each quackage-managed npm script for existence and value match
+3. Reports `[OK]` or `[NOT OK]` for each item
+4. For mismatched scripts, shows both the current and expected values
+
+No files are modified. Use `updatepackage` to apply fixes.
+
+## Example
+
+```bash
+quack lint
+```
+
+Output:
+
+```
+  --> mymodule:1.0.0/package.json SECTION { mocha:... }: [OK]
+  --> mymodule:1.0.0/package.json SCRIPT { scripts.test }: [OK]
+  --> mymodule:1.0.0/package.json SCRIPT { scripts.build }: [NOT OK]
+    > Current Script:  [webpack --mode production]
+    > Quackage Script: [npx quack build]
+```

package/docs/commands/package-management/luxuryupdatepackage.md

@@ -0,0 +1,44 @@
+# luxuryupdatepackage
+
+Add Docker-based luxury development environment scripts to your `package.json`.
+
+## Usage
+
+```bash
+quack luxuryupdatepackage [options]
+```
+
+Aliases: `luxury_update_package`, `lux`
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-f, --force` | Force overwrite existing scripts and sections. |
+
+## Behavior
+
+Works identically to `updatepackage` but manages the luxury (Docker) script set instead of the standard scripts. It:
+
+1. Reads the current `package.json`
+2. Adds any missing quackage-managed sections (same as `updatepackage`)
+3. Adds the Docker dev environment scripts (`docker-dev-build`, `docker-dev-run`, `docker-dev-shell`)
+4. Backs up to `.package.json.quackage.bak` before writing
+
+## Managed Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `docker-dev-build` | Build a Docker image from `Dockerfile_LUXURYCode` |
+| `docker-dev-run` | Run the dev container with mounted volumes and random ports |
+| `docker-dev-shell` | Open a bash shell in the running dev container |
+
+## Example
+
+```bash
+# Add Docker scripts to your project
+quack lux
+
+# Force overwrite existing Docker scripts
+quack lux --force
+```

package/docs/commands/package-management/updatepackage.md

@@ -0,0 +1,48 @@
+# updatepackage
+
+Add standard test, build, coverage and documentation scripts to your `package.json`.
+
+## Usage
+
+```bash
+quack updatepackage [options]
+```
+
+Aliases: `update_package`
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-f, --force` | Force overwrite existing scripts and sections. Use at your own quacking peril. |
+
+## Behavior
+
+1. Reads the current `package.json` from the working directory
+2. Compares each quackage-managed section (e.g. `mocha`) against the canonical defaults
+3. Compares each quackage-managed npm script against the canonical scripts
+4. Without `--force`: only adds sections and scripts that are missing; existing values are reported but not overwritten
+5. With `--force`: overwrites all managed sections and scripts regardless of current values
+6. Backs up the original `package.json` to `.package.json.quackage.bak`
+7. Writes the updated `package.json`
+
+## Managed Sections
+
+- `mocha` -- Mocha test runner configuration (TDD UI, spec reporter, 5s timeout)
+
+## Managed Scripts
+
+- `start`, `test`, `tests`, `coverage`, `build`, `docs`, `docs-serve`
+
+## Example
+
+```bash
+# See what would change (use lint first)
+quack lint
+
+# Add missing scripts
+quack updatepackage
+
+# Overwrite everything to match quackage defaults
+quack updatepackage --force
+```

package/docs/cover.md

@@ -0,0 +1,13 @@
+# Quackage
+
+> Building. Testing. Quacking. Reloading.
+
+A CLI toolkit for managing, building, testing and documenting JavaScript/Node.js modules. Quackage wraps common tools behind a consistent command interface so every module in your ecosystem follows the same conventions.
+
+- **Consistent** — One set of conventions for npm scripts, builds and documentation across all your modules
+- **Automated** — Generate configs, run builds, prepare docs and scaffold projects from templates
+- **Integrated** — Ties together Gulp, Mocha, Babel, Browserify, JSDoc, Indoctrinate and pict-docuserve
+
+[Get Started](README.md)
+[Command Reference](commands/documentation/README.md)
+[GitHub](https://github.com/stevenvelozo/quackage)

package/docs/css/docuserve.css

@@ -0,0 +1,73 @@
+/* ============================================================================
+   Pict Docuserve - Base Styles
+   ============================================================================ */
+
+/* Reset and base */
+*, *::before, *::after {
+	box-sizing: border-box;
+}
+
+html, body {
+	margin: 0;
+	padding: 0;
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+	font-size: 16px;
+	line-height: 1.5;
+	color: #423D37;
+	background-color: #fff;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+/* Typography */
+h1, h2, h3, h4, h5, h6 {
+	margin-top: 0;
+	line-height: 1.3;
+}
+
+a {
+	color: #2E7D74;
+	text-decoration: none;
+}
+
+a:hover {
+	color: #256861;
+}
+
+/* Application container */
+#Docuserve-Application-Container {
+	min-height: 100vh;
+}
+
+/* Utility: scrollbar styling */
+::-webkit-scrollbar {
+	width: 8px;
+}
+
+::-webkit-scrollbar-track {
+	background: #F5F0E8;
+}
+
+::-webkit-scrollbar-thumb {
+	background: #D4CCBE;
+	border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: #B5AA9A;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+	html {
+		font-size: 14px;
+	}
+
+	#Docuserve-Sidebar-Container {
+		display: none;
+	}
+
+	.docuserve-body {
+		flex-direction: column;
+	}
+}