Add cartridge minter tool

Author: hyperpolymath

tools/cartridge-minter/README.md

@@ -0,0 +1,62 @@
+# Cartridge Minter
+
+The Cartridge Minter is a tool for packaging, signing, and versioning cartridges for the BoJ server.
+
+## Features
+
+- Package cartridges into distributable artifacts
+- Generate A2ML manifests and panll descriptors
+- Sign cartridges for security and authenticity
+- Version cartridges using semantic versioning
+
+## Installation
+
+```bash
+cd tools/cartridge-minter
+npm install
+```
+
+## Usage
+
+### Command Line
+
+```bash
+node minter.js <cartridge-dir> <output-dir> [--sign] [--version <version>]
+```
+
+### Options
+
+- `<cartridge-dir>`: Path to the cartridge directory containing `cartridge.json`
+- `<output-dir>`: Path to the output directory for the minted cartridge
+- `--sign`: Sign the cartridge (placeholder for actual signing logic)
+- `--version <version>`: Specify the version of the cartridge (default: `0.1.0`)
+
+### Example
+
+```bash
+node minter.js ../../cartridges/my-cartridge output --sign --version 1.0.0
+```
+
+### Programmatic Usage
+
+```javascript
+import { mintCartridge } from './minter.js';
+
+const result = await mintCartridge('path/to/cartridge', 'path/to/output', {
+  sign: true,
+  version: '1.0.0',
+});
+
+console.log('Cartridge minted:', result);
+```
+
+## Output
+
+The Cartridge Minter generates the following files:
+
+- `<cartridge-name>.a2ml.json`: A2ML manifest for the cartridge
+- `<cartridge-name>.panll.json`: panll descriptor for the cartridge
+
+## License
+
+This tool is licensed under the PMPL-1.0-or-later license. See the LICENSE file for more information.

tools/cartridge-minter/minter.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+
+// Cartridge Minter — Package, sign, and version cartridges
+
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+
+async function readJsonFile(filePath) {
+  const content = await readFile(filePath, 'utf8');
+  return JSON.parse(content);
+}
+
+async function writeJsonFile(filePath, data) {
+  await writeFile(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+async function ensureDirectoryExists(directory) {
+  await mkdir(directory, { recursive: true });
+}
+
+async function mintCartridge(cartridgeDir, outputDir, options = {}) {
+  const { sign = false, version = '0.1.0' } = options;
+  
+  // Read cartridge.json
+  const cartridgeJsonPath = join(cartridgeDir, 'cartridge.json');
+  const cartridge = await readJsonFile(cartridgeJsonPath);
+  
+  // Update version
+  cartridge.version = version;
+  
+  // Generate A2ML Manifest
+  const a2mlManifest = {
+    spdx: 'PMPL-1.0-or-later',
+    name: cartridge.name,
+    version: cartridge.version,
+    description: cartridge.description,
+    domain: cartridge.domain,
+    tier: cartridge.tier,
+    protocols: cartridge.protocols,
+    tools: cartridge.tools,
+  };
+  
+  // Generate panll Descriptor
+  const panllDescriptor = {
+    name: cartridge.name,
+    version: cartridge.version,
+    description: cartridge.description,
+    domain: cartridge.domain,
+    tier: cartridge.tier,
+    protocols: cartridge.protocols,
+    tools: cartridge.tools,
+  };
+  
+  // Ensure output directory exists
+  await ensureDirectoryExists(outputDir);
+  
+  // Write A2ML Manifest
+  const a2mlManifestPath = join(outputDir, `${cartridge.name}.a2ml.json`);
+  await writeJsonFile(a2mlManifestPath, a2mlManifest);
+  
+  // Write panll Descriptor
+  const panllDescriptorPath = join(outputDir, `${cartridge.name}.panll.json`);
+  await writeJsonFile(panllDescriptorPath, panllDescriptor);
+  
+  // Sign the cartridge (placeholder for actual signing logic)
+  if (sign) {
+    console.log('Signing cartridge (placeholder)...');
+    // In a real implementation, you would use a tool like Sigstore or GPG to sign the cartridge
+  }
+  
+  return {
+    cartridge,
+    a2mlManifest,
+    panllDescriptor,
+    a2mlManifestPath,
+    panllDescriptorPath,
+  };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length < 2) {
+    console.error('Usage: node minter.js <cartridge-dir> <output-dir> [--sign] [--version <version>]');
+    process.exit(1);
+  }
+  
+  const cartridgeDir = args[0];
+  const outputDir = args[1];
+  const sign = args.includes('--sign');
+  const versionIndex = args.indexOf('--version');
+  const version = versionIndex !== -1 ? args[versionIndex + 1] : '0.1.0';
+  
+  try {
+    console.log(`Minting cartridge from ${cartridgeDir}...`);
+    const result = await mintCartridge(cartridgeDir, outputDir, { sign, version });
+    
+    console.log('Cartridge minted successfully:');
+    console.log(`  Name: ${result.cartridge.name}`);
+    console.log(`  Version: ${result.cartridge.version}`);
+    console.log(`  A2ML Manifest: ${result.a2mlManifestPath}`);
+    console.log(`  panll Descriptor: ${result.panllDescriptorPath}`);
+    
+    if (sign) {
+      console.log('  Signed: Yes');
+    }
+  } catch (error) {
+    console.error('Error minting cartridge:', error);
+    process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { mintCartridge };

tools/cartridge-minter/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "cartridge-minter",
+  "version": "0.1.0",
+  "description": "Cartridge Minter — Package, sign, and version cartridges",
+  "main": "minter.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["boj-server", "cartridge", "minter"],
+  "author": "Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>",
+  "license": "PMPL-1.0-or-later",
+  "type": "module"
+}