Add @appdmg/cli package

.github/workflows/ci.yml

@@ -10,8 +10,8 @@ on:
       - main
 
 jobs:
-  unit:
-    name: unit node v24 ${{ matrix.os }}
+  appdmg:
+    name: appdmg node v24 ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
 
     strategy:
@@ -45,3 +45,37 @@ jobs:
       - run: node --check lib/spec/validate.js
       - run: node --check test/errors.test.js
       - run: node --check test/library.test.js
+
+  cli:
+    name: cli node v24 ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-15-intel
+
+    defaults:
+      run:
+        working-directory: packages/cli
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: packages/cli/package-lock.json
+      - run: npm ci
+      - run: npm test
+      - run: npm audit --audit-level=moderate
+      - run: npm ls --omit=dev --all
+      - run: npm pack --dry-run
+      - run: node --check bin/appdmg-cli.js
+      - run: node --check lib/args.js
+      - run: node --check lib/main.js
+      - run: node --check lib/render-progress.js
+      - run: node --check test/args.test.js
+      - run: node --check test/main.test.js

packages/cli/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2012 Linus Unnebäck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/cli/README.md

@@ -0,0 +1,28 @@
+# @appdmg/cli
+
+Command line interface for `@appdmg/appdmg`.
+
+## Installation
+
+```sh
+npm install --global @appdmg/cli
+```
+
+## Usage
+
+```sh
+appdmg-cli <json-path> <dmg-path>
+```
+
+- `json-path`: path to the JSON specification file
+- `dmg-path`: path where the final DMG should be written
+
+The command writes human-readable output to stderr and writes nothing to
+stdout in this first stage.
+
+## Options
+
+- `--help`: print usage
+- `--version`: print the CLI package version
+- `--quiet`: suppress progress, success, and error output
+- `--verbose`, `-v`: print verbose diagnostics; this wins over `--quiet`

packages/cli/bin/appdmg-cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict'
+
+const appdmg = require('@appdmg/appdmg')
+const pkg = require('../package.json')
+const { main } = require('../lib/main')
+
+main({
+  argv: process.argv.slice(2),
+  appdmg,
+  pkg,
+  stdout: process.stdout,
+  stderr: process.stderr
+}).then((exitCode) => {
+  process.exitCode = exitCode
+}, (err) => {
+  process.stderr.write(`${err.stack || err.message}\n`)
+  process.exitCode = 1
+})

packages/cli/lib/args.js

@@ -0,0 +1,54 @@
+'use strict'
+
+const path = require('node:path')
+const { parseArgs } = require('node:util')
+
+function parseCliArgs (argv) {
+  const parsed = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: 'boolean' },
+      version: { type: 'boolean' },
+      quiet: { type: 'boolean' },
+      verbose: { type: 'boolean', short: 'v' }
+    }
+  })
+
+  const options = parsed.values
+  const positionals = parsed.positionals
+
+  if (options.help || options.version) {
+    return { options, positionals }
+  }
+
+  if (positionals.length < 2) {
+    throw new CliUsageError('Missing required arguments')
+  }
+
+  if (positionals.length > 2) {
+    throw new CliUsageError('Too many arguments')
+  }
+
+  if (path.extname(positionals[0]) !== '.json') {
+    throw new CliUsageError('Input must have the .json file extension')
+  }
+
+  if (path.extname(positionals[1]) !== '.dmg') {
+    throw new CliUsageError('Output must have the .dmg file extension')
+  }
+
+  return { options, positionals }
+}
+
+class CliUsageError extends Error {
+  constructor (message) {
+    super(message)
+    this.name = 'CliUsageError'
+  }
+}
+
+module.exports = {
+  CliUsageError,
+  parseCliArgs
+}

packages/cli/lib/main.js

@@ -0,0 +1,104 @@
+'use strict'
+
+const { CliUsageError, parseCliArgs } = require('./args')
+const { renderProgress } = require('./render-progress')
+
+const usage = [
+  'Generate DMG installer images for macOS applications.',
+  '',
+  'Usage: appdmg-cli <json-path> <dmg-path>',
+  '',
+  'json-path:  Path to the JSON specification file',
+  'dmg-path:   Path at which to place the final DMG',
+  '',
+  'Options:',
+  '',
+  '-v, --verbose',
+  '    Verbose error output',
+  '',
+  '--quiet',
+  '    Suppress progress, success, and error output',
+  '',
+  '--help',
+  '    Display usage and exit',
+  '',
+  '--version',
+  '    Display version and exit',
+  ''
+].join('\n')
+
+async function main (context) {
+  const stdout = context.stdout
+  const stderr = context.stderr
+  let parsed
+
+  try {
+    parsed = parseCliArgs(context.argv)
+  } catch (err) {
+    if (err instanceof CliUsageError) {
+      stderr.write(`${err.message}\n\n${usage}\n`)
+      return 1
+    }
+
+    stderr.write(`${err.message}\n`)
+    return 1
+  }
+
+  const options = parsed.options
+
+  if (options.version) {
+    stderr.write(`@appdmg/cli v${context.pkg.version}\n`)
+    return 0
+  }
+
+  if (options.help) {
+    stderr.write(`${usage}\n`)
+    return 0
+  }
+
+  const shouldWrite = !options.quiet || options.verbose
+  const source = parsed.positionals[0]
+  const target = parsed.positionals[1]
+  const image = context.appdmg({ source, target })
+
+  image.on('progress', (info) => {
+    if (!shouldWrite) return
+    stderr.write(renderProgress(info, stderr))
+  })
+
+  try {
+    await waitForImage(image)
+  } catch (err) {
+    if (shouldWrite) {
+      if (options.verbose && err.stack) {
+        stderr.write(`${err.stack}\n`)
+      } else {
+        stderr.write(`${err.name}: ${err.message}\n`)
+      }
+    }
+
+    return 1
+  }
+
+  if (shouldWrite) {
+    stderr.write(`\nYour image is ready:\n${target}\n`)
+  }
+
+  if (stdout && stdout.write) {
+    stdout.write('')
+  }
+
+  return 0
+}
+
+function waitForImage (image) {
+  return new Promise((resolve, reject) => {
+    image.once('finish', resolve)
+    image.once('error', reject)
+  })
+}
+
+module.exports = {
+  main,
+  usage
+}

packages/cli/lib/render-progress.js

@@ -0,0 +1,25 @@
+'use strict'
+
+function renderProgress (info, stream) {
+  if (info.type === 'step-begin') {
+    const current = String(info.current).padStart(2, ' ')
+    const line = `[${current}/${info.total}] ${info.title}...`
+    return line + ' '.repeat(Math.max(1, 45 - line.length))
+  }
+
+  if (info.type === 'step-end') {
+    const labels = {
+      ok: ' OK ',
+      skip: 'SKIP',
+      error: 'FAIL'
+    }
+
+    return `[${labels[info.status] || info.status}]\n`
+  }
+
+  return ''
+}
+
+module.exports = {
+  renderProgress
+}