@josstei/maestro 1.6.4-rc.1

package/scripts/npm-publish-idempotent.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function printHelp() {
+  console.log(`Publish a Maestro npm package if the exact version is absent.
+
+Usage:
+  node scripts/npm-publish-idempotent.js [--tag TAG] [--access public]
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    access: 'public',
+    tag: null,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+
+    if (arg === '--access') {
+      options.access = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--tag') {
+      options.tag = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (!options.access) {
+    throw new Error('Missing value for --access');
+  }
+
+  if (options.tag === undefined) {
+    throw new Error('Missing value for --tag');
+  }
+
+  return options;
+}
+
+function readPackage(root) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+
+  if (typeof pkg.name !== 'string' || pkg.name.length === 0) {
+    throw new Error('package.json missing package name');
+  }
+
+  if (typeof pkg.version !== 'string' || pkg.version.length === 0) {
+    throw new Error('package.json missing package version');
+  }
+
+  return pkg;
+}
+
+function isNpmNotFoundError(error) {
+  const text = [
+    error && error.message,
+    error && error.stdout && error.stdout.toString(),
+    error && error.stderr && error.stderr.toString(),
+  ].filter(Boolean).join('\n');
+
+  return /\bE404\b|404 Not Found|is not in this registry/i.test(text);
+}
+
+function packageVersionExists(packageSpec, runner) {
+  try {
+    const stdout = runner('npm', ['view', packageSpec, 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return stdout.toString().trim().length > 0;
+  } catch (error) {
+    if (isNpmNotFoundError(error)) {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+function publishIfNeeded(options = {}) {
+  const root = options.root || ROOT;
+  const runner = options.execFileSync || execFileSync;
+  const pkg = readPackage(root);
+  const packageSpec = `${pkg.name}@${pkg.version}`;
+
+  if (packageVersionExists(packageSpec, runner)) {
+    return {
+      packageSpec,
+      published: false,
+    };
+  }
+
+  const publishArgs = ['publish'];
+  if (options.tag) {
+    publishArgs.push('--tag', options.tag);
+  }
+  publishArgs.push('--access', options.access || 'public');
+
+  runner('npm', publishArgs, {
+    cwd: root,
+    stdio: 'inherit',
+  });
+
+  return {
+    packageSpec,
+    published: true,
+  };
+}
+
+if (require.main === module) {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    const result = publishIfNeeded(options);
+
+    if (result.published) {
+      console.log(`Published ${result.packageSpec}`);
+    } else {
+      console.log(`Skipping npm publish; ${result.packageSpec} already exists`);
+    }
+  } catch (error) {
+    console.error(`npm publish failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  isNpmNotFoundError,
+  packageVersionExists,
+  parseArgs,
+  publishIfNeeded,
+  readPackage,
+};

package/scripts/package-release-artifacts.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const {
+  RELEASE_ARTIFACT_PATHS,
+  assertRequiredArtifactPaths,
+  assertRuntimeManifestShape,
+  isDeniedPath,
+  readJson,
+  toPosixPath,
+} = require('./release-artifact-manifest');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function printHelp() {
+  console.log(`Package Maestro release artifacts.
+
+Usage:
+  node scripts/package-release-artifacts.js [--version X.Y.Z] [--out-dir dist/release]
+
+Options:
+  --version  Version to package. Defaults to package.json version.
+  --out-dir  Directory for the generated archive. Defaults to dist/release.
+  --help     Show this help text.
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    version: null,
+    outDir: 'dist/release',
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+
+    if (arg === '--version') {
+      options.version = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--out-dir') {
+      options.outDir = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (options.version === undefined || options.outDir === undefined) {
+    throw new Error('Missing value for release artifact option');
+  }
+
+  return options;
+}
+
+function resolveVersion(root, requestedVersion) {
+  const packageVersion = readJson(root, 'package.json').version;
+  const version = requestedVersion || packageVersion;
+
+  if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`Invalid release artifact version: ${version}`);
+  }
+
+  return version;
+}
+
+function copyPath(root, stagingRoot, relativePath) {
+  if (isDeniedPath(relativePath)) {
+    throw new Error(`Refusing to package denied path: ${relativePath}`);
+  }
+
+  const sourcePath = path.join(root, relativePath);
+  const targetPath = path.join(stagingRoot, relativePath);
+  const sourceStat = fs.statSync(sourcePath);
+
+  if (sourceStat.isDirectory()) {
+    fs.cpSync(sourcePath, targetPath, {
+      recursive: true,
+      filter: (source) => {
+        const sourceRelativePath = toPosixPath(path.relative(root, source));
+        return !sourceRelativePath || !isDeniedPath(sourceRelativePath);
+      },
+    });
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.copyFileSync(sourcePath, targetPath);
+  fs.chmodSync(targetPath, sourceStat.mode);
+}
+
+function createTarball(stagingRoot, archivePath) {
+  fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+  fs.rmSync(archivePath, { force: true });
+
+  execFileSync('tar', ['-czf', archivePath, '-C', stagingRoot, '.'], {
+    stdio: 'inherit',
+  });
+}
+
+function packageReleaseArtifacts(options = {}) {
+  const root = options.root || ROOT;
+  const version = resolveVersion(root, options.version || null);
+  const outDir = path.resolve(root, options.outDir || 'dist/release');
+  const archivePath = path.join(outDir, `maestro-v${version}-extension.tar.gz`);
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'maestro-release-artifact-'));
+  const stagingRoot = path.join(tempRoot, 'maestro');
+
+  try {
+    assertRequiredArtifactPaths(root);
+    assertRuntimeManifestShape(root, version);
+    fs.mkdirSync(stagingRoot, { recursive: true });
+
+    for (const relativePath of RELEASE_ARTIFACT_PATHS) {
+      copyPath(root, stagingRoot, relativePath);
+    }
+
+    assertRuntimeManifestShape(stagingRoot, version);
+    createTarball(stagingRoot, archivePath);
+
+    return {
+      archivePath,
+      version,
+    };
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+if (require.main === module) {
+  try {
+    const result = packageReleaseArtifacts(parseArgs(process.argv.slice(2)));
+    console.log(`Created release artifact: ${path.relative(ROOT, result.archivePath)}`);
+  } catch (error) {
+    console.error(`release artifact packaging failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  packageReleaseArtifacts,
+  parseArgs,
+  resolveVersion,
+};

package/scripts/release-artifact-manifest.js

@@ -0,0 +1,378 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RELEASE_ARTIFACT_PATHS = [
+  '.agents/plugins/marketplace.json',
+  '.claude-plugin/marketplace.json',
+  'CHANGELOG.md',
+  'EXAMPLES.md',
+  'GEMINI.md',
+  'LICENSE',
+  'QWEN.md',
+  'README.md',
+  'agents',
+  'bin',
+  'claude',
+  'commands',
+  'docs/runtime-gemini.md',
+  'docs/runtime-claude.md',
+  'docs/runtime-codex.md',
+  'docs/runtime-qwen.md',
+  'docs/usage.md',
+  'gemini-extension.json',
+  'hooks',
+  'mcp',
+  'package-lock.json',
+  'package.json',
+  'plugins/maestro',
+  'policies',
+  'qwen',
+  'qwen-extension.json',
+  'src',
+];
+
+const DENIED_ARTIFACT_PATHS = [
+  '.git',
+  '.github',
+  '.gemini',
+  '.gemini_security',
+  '.claude',
+  '.worktrees',
+  '.serena',
+  '.superpowers',
+  'coverage',
+  'dist',
+  'docs/maestro',
+  'docs/superpowers',
+  'node_modules',
+  'tests',
+  'tmp',
+  'temp',
+  'hooks/permissions.json',
+];
+
+const DENIED_ARTIFACT_PATTERNS = [
+  /(^|\/)__tests__(\/|$)/,
+  /\.spec\.[cm]?js$/,
+  /\.test\.[cm]?js$/,
+];
+
+const REQUIRED_PACKAGE_FILES = [
+  'bin/maestro-mcp-server.js',
+  'claude/.claude-plugin/plugin.json',
+  'gemini-extension.json',
+  'plugins/maestro/.codex-plugin/plugin.json',
+  'qwen-extension.json',
+  'src/mcp/maestro-server.js',
+];
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+function normalizeArtifactPath(relativePath) {
+  const normalized = toPosixPath(relativePath).replace(/\/+$/, '');
+  return normalized === '.' ? '' : normalized.replace(/^\.\//, '');
+}
+
+function isDeniedPath(relativePath) {
+  const normalized = normalizeArtifactPath(relativePath);
+  const deniedByPath = DENIED_ARTIFACT_PATHS.some((denied) => {
+    return normalized === denied || normalized.startsWith(`${denied}/`);
+  });
+
+  return deniedByPath || DENIED_ARTIFACT_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+function isReleaseArtifactPathAllowed(relativePath) {
+  const normalized = normalizeArtifactPath(relativePath);
+
+  if (!normalized) {
+    return true;
+  }
+
+  return RELEASE_ARTIFACT_PATHS.some((allowed) => {
+    return (
+      normalized === allowed ||
+      normalized.startsWith(`${allowed}/`) ||
+      allowed.startsWith(`${normalized}/`)
+    );
+  });
+}
+
+function ensureInsideRoot(root, targetPath) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(targetPath);
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Path escapes repository root: ${targetPath}`);
+  }
+}
+
+function assertRequiredArtifactPaths(root) {
+  const missing = [];
+
+  for (const relativePath of RELEASE_ARTIFACT_PATHS) {
+    if (isDeniedPath(relativePath)) {
+      throw new Error(`Release artifact allowlist contains denied path: ${relativePath}`);
+    }
+
+    const sourcePath = path.join(root, relativePath);
+    ensureInsideRoot(root, sourcePath);
+
+    if (!fs.existsSync(sourcePath)) {
+      missing.push(relativePath);
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(`Required release artifact paths are missing: ${missing.join(', ')}`);
+  }
+}
+
+function walkArtifactFiles(root) {
+  const files = [];
+  const queue = ['.'];
+
+  while (queue.length > 0) {
+    const relativeDir = queue.pop();
+    const absoluteDir = path.join(root, relativeDir);
+
+    for (const entry of fs.readdirSync(absoluteDir, { withFileTypes: true })) {
+      const relativePath = normalizeArtifactPath(path.posix.join(relativeDir, entry.name));
+      files.push(relativePath);
+
+      if (entry.isDirectory()) {
+        queue.push(relativePath);
+      }
+    }
+  }
+
+  return files.sort();
+}
+
+function assertReleaseArtifactContents(root) {
+  const denied = [];
+  const unexpected = [];
+
+  for (const relativePath of walkArtifactFiles(root)) {
+    if (isDeniedPath(relativePath)) {
+      denied.push(relativePath);
+      continue;
+    }
+
+    if (!isReleaseArtifactPathAllowed(relativePath)) {
+      unexpected.push(relativePath);
+    }
+  }
+
+  if (denied.length > 0) {
+    throw new Error(`Release artifact contains denied paths: ${denied.join(', ')}`);
+  }
+
+  if (unexpected.length > 0) {
+    throw new Error(`Release artifact contains unallowlisted paths: ${unexpected.join(', ')}`);
+  }
+}
+
+function readJson(root, relativePath) {
+  const filePath = path.join(root, relativePath);
+  let parsed;
+
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${relativePath}: ${error.message}`);
+  }
+
+  return parsed;
+}
+
+function requireVersion(value, label) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing version value for ${label}`);
+  }
+
+  return value;
+}
+
+function requireString(value, label) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing string value for ${label}`);
+  }
+
+  return value;
+}
+
+function findNamedPlugin(marketplace, name, relativePath) {
+  if (!Array.isArray(marketplace.plugins)) {
+    throw new Error(`${relativePath} must contain a plugins array`);
+  }
+
+  const plugin = marketplace.plugins.find((entry) => entry && entry.name === name);
+  if (!plugin) {
+    throw new Error(`${relativePath} missing plugin entry "${name}"`);
+  }
+
+  return plugin;
+}
+
+function getVersionEntries(root) {
+  const pkg = readJson(root, 'package.json');
+  const gemini = readJson(root, 'gemini-extension.json');
+  const qwen = readJson(root, 'qwen-extension.json');
+  const claudePlugin = readJson(root, 'claude/.claude-plugin/plugin.json');
+  const codexPlugin = readJson(root, 'plugins/maestro/.codex-plugin/plugin.json');
+  const claudeMarketplace = readJson(root, '.claude-plugin/marketplace.json');
+  const claudeSrcVersion = readJson(root, 'claude/src/version.json');
+  const codexSrcVersion = readJson(root, 'plugins/maestro/src/version.json');
+  const claudeMarketplacePlugin = findNamedPlugin(
+    claudeMarketplace,
+    'maestro',
+    '.claude-plugin/marketplace.json'
+  );
+
+  return [
+    ['package.json', requireVersion(pkg.version, 'package.json')],
+    ['gemini-extension.json', requireVersion(gemini.version, 'gemini-extension.json')],
+    ['qwen-extension.json', requireVersion(qwen.version, 'qwen-extension.json')],
+    ['claude/.claude-plugin/plugin.json', requireVersion(claudePlugin.version, 'claude plugin')],
+    ['plugins/maestro/.codex-plugin/plugin.json', requireVersion(codexPlugin.version, 'Codex plugin')],
+    ['.claude-plugin/marketplace.json metadata.version', requireVersion(claudeMarketplace.metadata && claudeMarketplace.metadata.version, 'Claude marketplace metadata')],
+    ['.claude-plugin/marketplace.json plugins.maestro.version', requireVersion(claudeMarketplacePlugin.version, 'Claude marketplace plugin')],
+    ['claude/src/version.json', requireVersion(claudeSrcVersion.version, 'Claude detached payload')],
+    ['plugins/maestro/src/version.json', requireVersion(codexSrcVersion.version, 'Codex detached payload')],
+  ];
+}
+
+function assertVersionConsistency(root, expectedVersion = null) {
+  const entries = getVersionEntries(root);
+  const baseline = expectedVersion || entries[0][1];
+  const mismatches = entries.filter(([, version]) => version !== baseline);
+
+  if (mismatches.length > 0) {
+    const details = mismatches.map(([label, version]) => `${label}=${version}`).join(', ');
+    throw new Error(`Release manifest version mismatch; expected ${baseline}: ${details}`);
+  }
+
+  return baseline;
+}
+
+function assertRuntimeManifestShape(root, expectedVersion = null) {
+  const version = assertVersionConsistency(root, expectedVersion);
+  const pkg = readJson(root, 'package.json');
+  const gemini = readJson(root, 'gemini-extension.json');
+  const qwen = readJson(root, 'qwen-extension.json');
+  const claudeMarketplace = readJson(root, '.claude-plugin/marketplace.json');
+  const codexMarketplace = readJson(root, '.agents/plugins/marketplace.json');
+  const claudePlugin = readJson(root, 'claude/.claude-plugin/plugin.json');
+  const codexPlugin = readJson(root, 'plugins/maestro/.codex-plugin/plugin.json');
+  const claudeMcp = readJson(root, 'claude/.mcp.json');
+  const codexMcp = readJson(root, 'plugins/maestro/.mcp.json');
+
+  const packageName = requireString(pkg.name, 'package.json name');
+
+  const claudeMarketplacePlugin = findNamedPlugin(
+    claudeMarketplace,
+    'maestro',
+    '.claude-plugin/marketplace.json'
+  );
+  if (claudeMarketplacePlugin.source !== './claude') {
+    throw new Error('.claude-plugin/marketplace.json maestro source must be ./claude');
+  }
+
+  const codexMarketplacePlugin = findNamedPlugin(
+    codexMarketplace,
+    'maestro',
+    '.agents/plugins/marketplace.json'
+  );
+  if (
+    !codexMarketplacePlugin.source ||
+    codexMarketplacePlugin.source.source !== 'local' ||
+    codexMarketplacePlugin.source.path !== './plugins/maestro'
+  ) {
+    throw new Error('.agents/plugins/marketplace.json maestro source must be local ./plugins/maestro');
+  }
+
+  if (gemini.contextFileName !== 'GEMINI.md' || !gemini.mcpServers || !gemini.mcpServers.maestro) {
+    throw new Error('gemini-extension.json must define GEMINI.md and maestro MCP server');
+  }
+
+  if (qwen.contextFileName !== 'QWEN.md' || !qwen.mcpServers || !qwen.mcpServers.maestro) {
+    throw new Error('qwen-extension.json must define QWEN.md and maestro MCP server');
+  }
+
+  if (claudePlugin.hooks !== './hooks/claude-hooks.json') {
+    throw new Error('claude plugin manifest must reference ./hooks/claude-hooks.json');
+  }
+
+  if (
+    codexPlugin.skills !== './skills/' ||
+    codexPlugin.mcpServers !== './.mcp.json' ||
+    codexPlugin.apps !== './.app.json'
+  ) {
+    throw new Error('Codex plugin manifest must reference skills, MCP, and app config files');
+  }
+
+  const claudeServer = claudeMcp.mcpServers && claudeMcp.mcpServers.maestro;
+  if (
+    !claudeServer ||
+    claudeServer.command !== 'node' ||
+    !Array.isArray(claudeServer.args) ||
+    !claudeServer.args.includes('${CLAUDE_PLUGIN_ROOT}/mcp/maestro-server.js')
+  ) {
+    throw new Error('claude/.mcp.json must launch the bundled Maestro MCP server');
+  }
+
+  const codexServer = codexMcp.mcpServers && codexMcp.mcpServers.maestro;
+  const expectedPackageSpec = `${packageName}@${version}`;
+  if (
+    !codexServer ||
+    codexServer.command !== 'npx' ||
+    !Array.isArray(codexServer.args) ||
+    !codexServer.args.includes('-p') ||
+    !codexServer.args.includes(expectedPackageSpec) ||
+    !codexServer.args.includes('maestro-mcp-server')
+  ) {
+    throw new Error(`plugins/maestro/.mcp.json must launch ${expectedPackageSpec}`);
+  }
+
+  const requiredRuntimeFiles = [
+    'bin/maestro-mcp-server.js',
+    'claude/src/mcp/maestro-server.js',
+    'plugins/maestro/src/mcp/maestro-server.js',
+  ];
+
+  for (const relativePath of requiredRuntimeFiles) {
+    if (!fs.existsSync(path.join(root, relativePath))) {
+      throw new Error(`Required runtime file missing: ${relativePath}`);
+    }
+  }
+
+  const binMode = fs.statSync(path.join(root, 'bin/maestro-mcp-server.js')).mode;
+  if ((binMode & 0o111) === 0) {
+    throw new Error('bin/maestro-mcp-server.js must be executable');
+  }
+
+  return version;
+}
+
+module.exports = {
+  DENIED_ARTIFACT_PATHS,
+  DENIED_ARTIFACT_PATTERNS,
+  RELEASE_ARTIFACT_PATHS,
+  REQUIRED_PACKAGE_FILES,
+  assertReleaseArtifactContents,
+  assertRequiredArtifactPaths,
+  assertRuntimeManifestShape,
+  assertVersionConsistency,
+  getVersionEntries,
+  isDeniedPath,
+  isReleaseArtifactPathAllowed,
+  requireString,
+  readJson,
+  toPosixPath,
+};