@budhash/zap-sh

A JavaScript generator for zap-sh scripts. It produces the same output as the bash zap-sh init command, byte-for-byte: a shared conformance suite runs the same fixtures through both the bash and JS generators in CI, so their output stays in sync. See the generation spec.

It covers init (generation) only — template choice, project metadata, license, and variable substitution. Use the bash tool for update, snip, and upgrade.

Install

npm install @budhash/zap-sh

Usage

import { generate } from '@budhash/zap-sh';

const { filename, content } = generate({
  template: 'enhanced',          // 'basic' | 'enhanced'
  project: 'my-tool',            // becomes {{app}}; /^[a-zA-Z0-9_-]+$/
  license: 'mit',                // 'mit' | 'apache' | 'gpl' (optional)
  year: '2025',                  // pins {{year}} (optional; defaults to current year)
  variables: {                   // extra {{key}} values; order is significant
    author: 'Jane Doe',
    email: '[email protected]',
    version: '1.2.0',
    detail: 'Short description',
    description: 'Longer description',
  },
});

// content === what `zap-sh init my-tool -t enhanced --license=mit ...` writes
// filename === 'my-tool.sh'

CommonJS works too:

const { generate } = require('@budhash/zap-sh');

API

• generate(options) => { filename, content } — generate a script. Throws on an invalid template, project name, variable name, or license code.
• substitute(content, pairs) — the {{key}} substitution engine (sequential, whole-buffer; see SPEC §4).
• extractSection(templateText, name) — extract a ##( name … ##) name section (markers included), or null.
• listTemplates() / listLicenses() — available names / license codes.

Full types in types/index.d.ts.

Determinism

year is the only clock-derived input. Pass year to make output fully reproducible; omit it to use the current year. See SPEC §6 for the one edge ({{year}} embedded inside a field value) that remains clock-bound.

Development

The templates are bundled from the repo's templates/ at build time (the single source of truth), so src/templates.generated.js and dist/ are generated.

npm run build     # bundle templates + emit dist/index.mjs + dist/index.cjs (pure Node, no deps)
npm test          # build, then conformance vs the shared golden files
npm run test:diff # differential parity: run the live bash tool + JS and diff

The package has zero dependencies — the build is plain Node (no bundler).

Parity is enforced in CI two ways: the JS and bash conformance runners both check the same fixtures in test/conformance/, and the differential test runs the live zap-sh init and the JS generator over a broad input matrix and compares byte-for-byte.