README.md emit.js info

2026-09-09 13:18:29 -04:00
parent e99389d78d
commit 8c228b731a
1 changed files with 29 additions and 0 deletions
@@ -3,3 +3,32 @@
 * emit.js will scaffold a dir or update files that are already there
 * gen.js is the build script that builds to the target dir
 * serve.js is a local server for your cards interface
+
+# emit.mjs
+
+`emit.mjs` is the deployment adapter projection engine. It reconciles engine-level deployment templates with target-specific instance directories, preserving user configuration while propagating structural template updates.
+
+## Usage
+
+\`\`\`bash
+node engine/emit.mjs <target> <dir>
+\`\`\`
+
+* **`<target>`**: The deploy plugin directory located inside `engine/` (e.g., `cloudflare`).
+* **`<dir>`**: The target instance directory where the adapter files will be projected.
+
+## Core Principles
+
+* **Rebuild & Preserve**: Reads per-target configuration values (such as `name` and `TITLE`) out of existing target files (`wrangler.toml`), then regenerates all adapter files from the plugin templates carrying those values. Structural template changes automatically propagate on every run.
+* **Authored Content Protection**: The `content/` directory is authored data—it is never generated, overwritten, or touched by the emitter.
+* **Manifest Generation**: Automatically invokes the engine's `gen.mjs` script against the target's `content/` directory to build the `_manifest.js` index.
+
+## Workflow Execution
+
+1. **Validation**: Verifies that both arguments are provided and that the specified deploy plugin exists under the engine path.
+2. **Configuration Extraction**: Scans the existing target configuration (`wrangler.toml`) for pre-existing custom tokens like `NAME` and `TITLE`. If absent, defaults to template placeholders (`{{NAME}}`, `{{TITLE}}`).
+3. **Adapter Projection**: Iterates over all files in the plugin directory, maps special names (such as converting `gitignore` to `.gitignore`), injects the preserved configuration values, and writes them out to the target directory. Ensures the `content/` directory structure exists without altering its contents.
+4. **Manifest Compilation**: Executes `gen.mjs` within the context of the target directory to rebuild `_manifest.js` from the authored content.
+5. **Scaffolding Notice**: Reports success and alerts the user if any required placeholder variables still need to be filled in prior to deployment.
+
+