feat(ansible-example): add @ansible/example package, tests, CI, publish & deploy workflows, docs and changelog

packages/@ansible/example/README.md

@@ -0,0 +1,18 @@
+# @ansible/example
+
+A minimal example npm-scoped package for the @ansible scope. Provided as a publishable example maintained by Sven Geboers.
+
+Usage:
+
+const example = require('@ansible/example');
+console.log(example('world'));
+
+Author: Sven Geboers
+
+Publishing
+
+This package is intended to be published from CI using a repository secret named NPM_TOKEN. Create a git tag (e.g. `v0.1.0`) and push it; the GitHub Actions workflow will run and publish when `NPM_TOKEN` is configured. For local testing, run `npm pack` in the package directory.
+
+Refer to the repository docs for full deploy and publish instructions.
+
+Make sure to keep this README short and useful.

packages/@ansible/example/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@ansible/example",
+  "version": "1.0.0",
+  "author": "Sven Geboers <sven@example.com>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "lib"
+  ]
+  ,
+  "scripts": {
+    "test": "node tests/run.js"
+  }
+}

packages/@ansible/example/src/index.js

@@ -0,0 +1,8 @@
+// Minimal entrypoint for @ansible/example
+module.exports = function example(name) {
+  if (!name) return 'hello';
+  return `hello ${name}`;
+};
+
+// When required directly, export a default behaviour too
+module.exports.default = module.exports;

packages/@ansible/example/tests/_pack_helpers.js

@@ -0,0 +1,11 @@
+const { execSync } = require('child_process');
+const path = require('path');
+module.exports.runPack = function runPack() {
+  const cwd = path.join(__dirname, '..');
+  // run npm pack and capture output
+  const out = execSync('npm pack', { cwd, encoding: 'utf8' }).trim();
+  // npm pack prints the filename on the last line
+  const lines = out.split(/\r?\n/).filter(Boolean);
+  const filename = lines[lines.length - 1];
+  return { cwd, filename };
+};

packages/@ansible/example/tests/run.js

@@ -0,0 +1,20 @@
+const { execSync } = require('child_process');
+const path = require('path');
+const tests = [
+  'test_package_json.js',
+  'test_pack_inspect.js'
+];
+
+const cwd = path.join(__dirname);
+let failed = false;
+for (const t of tests) {
+  console.log('Running', t);
+  try {
+    execSync(`node ${t}`, { cwd, stdio: 'inherit' });
+  } catch (e) {
+    console.error(t, 'failed');
+    failed = true;
+    break;
+  }
+}
+process.exit(failed ? 1 : 0);

packages/@ansible/example/tests/test_pack_inspect.js

@@ -0,0 +1,28 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { runPack } = require('./_pack_helpers');
+try {
+  const { cwd, filename } = runPack();
+  const tarPath = path.join(cwd, filename);
+  if (!fs.existsSync(tarPath)) throw new Error('tarball not found: ' + tarPath);
+  // inspect package/package.json within tarball using tar -xOzf
+  const execSync = require('child_process').execSync;
+  let pkgJsonStr;
+  try {
+    pkgJsonStr = execSync(`tar -xOzf ${filename} package/package.json`, { cwd, encoding: 'utf8' });
+  } catch (e) {
+    throw new Error('failed to extract package.json from tarball; ensure `tar` is available');
+  }
+  const pkg = JSON.parse(pkgJsonStr);
+  assert.strictEqual(pkg.name, '@ansible/example', 'tarball package.json name mismatch');
+  assert.ok(pkg.version, 'tarball package.json missing version');
+  console.log('test_pack_inspect: OK');
+  // cleanup: remove tarball
+  try { fs.unlinkSync(tarPath); } catch (e) {}
+  process.exit(0);
+} catch (err) {
+  console.error('test_pack_inspect: FAILED');
+  console.error(err && err.message ? err.message : err);
+  process.exit(1);
+}

packages/@ansible/example/tests/test_package_json.js

@@ -0,0 +1,17 @@
+const assert = require('assert');
+const path = require('path');
+const pkg = require(path.join(__dirname, '..', 'package.json'));
+
+try {
+  assert.strictEqual(pkg.name, '@ansible/example', 'package name must be @ansible/example');
+  assert.ok(pkg.version && typeof pkg.version === 'string', 'version must be present');
+  assert.ok(pkg.author && pkg.author.includes('Sven'), 'author must be Sven Geboers');
+  assert.ok(pkg.publishConfig && pkg.publishConfig.access === 'public', 'publishConfig.access must be public');
+  assert.ok(Array.isArray(pkg.files), 'files array must exist');
+  console.log('test_package_json: OK');
+  process.exit(0);
+} catch (err) {
+  console.error('test_package_json: FAILED');
+  console.error(err && err.message ? err.message : err);
+  process.exit(1);
+}