skill-automation-package 0.2.0

package/bin/skill-automation-package.js

@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { spawn, spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const MIN_PYTHON = { major: 3, minor: 10 };
+const INSTALL_METADATA_PATH = path.join(".claude", "skill-automation-package.json");
+
+function main() {
+  const [, , subcommand, ...forwardedArgs] = process.argv;
+
+  if (subcommand !== "install" && subcommand !== "update") {
+    printUsage(subcommand);
+    process.exitCode = 1;
+    return;
+  }
+
+  const packageRoot = path.resolve(__dirname, "..");
+  const installerPath = path.resolve(packageRoot, "scripts", "install.py");
+  if (!fs.existsSync(installerPath)) {
+    console.error(
+      `skill-automation-package: expected installer at ${installerPath}, but it was not found.`,
+    );
+    console.error("Reinstall the package or run it from a complete package checkout.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const packageInfo = readPackageInfo(packageRoot);
+  if (!packageInfo.ok) {
+    console.error(packageInfo.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  const targetRoot = resolveTargetRoot(forwardedArgs);
+  if (subcommand === "update" && !targetRoot) {
+    console.error("skill-automation-package: update requires --target <repo>.");
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const installState = targetRoot ? detectInstallState(targetRoot, packageInfo.version) : null;
+  if (subcommand === "update") {
+    const updateDecision = handleUpdateState(installState, packageInfo.version);
+    if (updateDecision === "stop-success") {
+      process.exitCode = 0;
+      return;
+    }
+    if (updateDecision === "stop-failure") {
+      process.exitCode = 1;
+      return;
+    }
+  } else if (installState) {
+    printInstallState(installState, packageInfo.version);
+  }
+
+  const python = findPython();
+  if (!python.ok) {
+    printPythonError(python);
+    process.exitCode = 1;
+    return;
+  }
+
+  const child = spawn(python.command, [...python.args, installerPath, ...forwardedArgs], {
+    stdio: "inherit",
+  });
+
+  child.on("error", (error) => {
+    console.error(`skill-automation-package: failed to launch ${python.display}.`);
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code === null ? 1 : code;
+  });
+}
+
+function readPackageInfo(packageRoot) {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return {
+      ok: false,
+      message: `skill-automation-package: expected package metadata at ${packageJsonPath}, but it was not found.`,
+    };
+  }
+
+  try {
+    const raw = fs.readFileSync(packageJsonPath, "utf8");
+    const manifest = JSON.parse(raw);
+    if (typeof manifest.version !== "string" || manifest.version.trim() === "") {
+      return {
+        ok: false,
+        message: `skill-automation-package: package metadata at ${packageJsonPath} does not contain a valid version string.`,
+      };
+    }
+    return { ok: true, version: manifest.version.trim() };
+  } catch (error) {
+    return {
+      ok: false,
+      message: `skill-automation-package: failed to read package metadata from ${packageJsonPath}: ${error.message}`,
+    };
+  }
+}
+
+function resolveTargetRoot(forwardedArgs) {
+  let targetValue = null;
+
+  for (let index = 0; index < forwardedArgs.length; index += 1) {
+    const argument = forwardedArgs[index];
+
+    if (argument === "--target" && index + 1 < forwardedArgs.length) {
+      targetValue = forwardedArgs[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (argument.startsWith("--target=")) {
+      targetValue = argument.slice("--target=".length);
+    }
+  }
+
+  if (!targetValue) {
+    return null;
+  }
+
+  return path.resolve(process.cwd(), targetValue);
+}
+
+function detectInstallState(targetRoot, currentVersion) {
+  const metadataPath = path.join(targetRoot, INSTALL_METADATA_PATH);
+  if (!fs.existsSync(metadataPath)) {
+    return { status: "not-installed", targetRoot, metadataPath };
+  }
+
+  try {
+    const raw = fs.readFileSync(metadataPath, "utf8");
+    const metadata = JSON.parse(raw);
+    if (typeof metadata.version !== "string" || metadata.version.trim() === "") {
+      return { status: "unknown", targetRoot, metadataPath, reason: "missing-version" };
+    }
+
+    const installedVersion = metadata.version.trim();
+    const installedParsed = parseVersion(installedVersion);
+    const currentParsed = parseVersion(currentVersion);
+    if (!installedParsed || !currentParsed) {
+      return { status: "unknown", targetRoot, metadataPath, installedVersion, reason: "invalid-version" };
+    }
+
+    const comparison = compareVersions(installedParsed, currentParsed);
+    if (comparison === 0) {
+      return { status: "same-version", targetRoot, metadataPath, installedVersion };
+    }
+    if (comparison < 0) {
+      return { status: "update-available", targetRoot, metadataPath, installedVersion };
+    }
+    return { status: "newer-installed", targetRoot, metadataPath, installedVersion };
+  } catch (_error) {
+    return { status: "unknown", targetRoot, metadataPath, reason: "invalid-json" };
+  }
+}
+
+function compareVersions(left, right) {
+  if (left.major !== right.major) {
+    return left.major - right.major;
+  }
+  if (left.minor !== right.minor) {
+    return left.minor - right.minor;
+  }
+  return left.patch - right.patch;
+}
+
+function printInstallState(state, currentVersion) {
+  switch (state.status) {
+    case "not-installed":
+      console.log(
+        `skill-automation-package: target is not installed yet; proceeding with install of version ${currentVersion}.`,
+      );
+      return;
+    case "same-version":
+      console.log(
+        `skill-automation-package: target is already at version ${state.installedVersion}; reinstalling anyway.`,
+      );
+      printReinstallSafety();
+      return;
+    case "update-available":
+      console.log(
+        `skill-automation-package: update available: ${state.installedVersion} -> ${currentVersion}`,
+      );
+      printReinstallSafety();
+      return;
+    case "newer-installed":
+      console.log(
+        `skill-automation-package: target reports version ${state.installedVersion}, which is newer than this package version ${currentVersion}.`,
+      );
+      console.log(
+        `skill-automation-package: reinstalling will replace packaged files with version ${currentVersion}.`,
+      );
+      printReinstallSafety();
+      return;
+    default:
+      console.log(describeUnknownMetadata(state, "install", currentVersion));
+      printLifecycleSafety();
+  }
+}
+
+function handleUpdateState(state, currentVersion) {
+  switch (state.status) {
+    case "not-installed":
+      console.error("skill-automation-package: target is not installed; use install instead.");
+      return "stop-failure";
+    case "same-version":
+      console.log(`skill-automation-package: already up to date (${currentVersion}).`);
+      return "stop-success";
+    case "update-available":
+      console.log(`skill-automation-package: updating ${state.installedVersion} -> ${currentVersion}`);
+      printLifecycleSafety();
+      return "proceed";
+    case "newer-installed":
+      console.error(
+        `skill-automation-package: target reports version ${state.installedVersion}, which is newer than this package version ${currentVersion}.`,
+      );
+      console.error(
+        "skill-automation-package: update is blocked to avoid an implicit downgrade.",
+      );
+      return "stop-failure";
+    default:
+      console.error(describeUnknownMetadata(state, "update", currentVersion));
+      return "stop-failure";
+  }
+}
+
+function printReinstallSafety() {
+  printLifecycleSafety();
+}
+
+function printLifecycleSafety() {
+  console.log("skill-automation-package: packaged files will be overwritten.");
+  console.log(
+    "skill-automation-package: repo-local skills, usage tracking, and archived skills will be preserved.",
+  );
+}
+
+function describeUnknownMetadata(state, mode, currentVersion) {
+  const metadataPath = state?.metadataPath || INSTALL_METADATA_PATH;
+  const reasonLabel = {
+    "invalid-json": "could not be parsed as JSON",
+    "missing-version": "does not contain a usable version",
+    "invalid-version": "contains a version that could not be compared",
+  };
+  const detail = reasonLabel[state?.reason] || "could not be compared";
+
+  if (mode === "install") {
+    return `skill-automation-package: existing install metadata at ${metadataPath} ${detail}; reinstalling with version ${currentVersion}.`;
+  }
+
+  return `skill-automation-package: existing install metadata at ${metadataPath} ${detail}; use install to force a reinstall.`;
+}
+
+function printUsage(subcommand) {
+  if (subcommand) {
+    console.error(`skill-automation-package: unsupported subcommand "${subcommand}".`);
+  }
+  console.error(
+    "Usage: skill-automation-package <install|update> --target <repo> [installer options]",
+  );
+  console.error("`install` always reinstalls. `update` is version-aware and may no-op.");
+}
+
+function findPython() {
+  const candidates = [
+    { command: "python3", args: [], display: "python3" },
+    { command: "python", args: [], display: "python" },
+  ];
+
+  if (process.platform === "win32") {
+    candidates.push({ command: "py", args: ["-3"], display: "py -3" });
+  }
+
+  const unsuitable = [];
+
+  for (const candidate of candidates) {
+    const probe = probePython(candidate);
+    if (probe.ok) {
+      return probe;
+    }
+    if (probe.reason === "version") {
+      unsuitable.push(probe);
+    }
+  }
+
+  if (unsuitable.length > 0) {
+    return { ok: false, reason: "version", unsuitable };
+  }
+
+  return { ok: false, reason: "missing", attempted: candidates.map((candidate) => candidate.display) };
+}
+
+function probePython(candidate) {
+  const versionScript =
+    "import sys; print(f'{sys.version_info[0]}.{sys.version_info[1]}.{sys.version_info[2]}')";
+  const result = spawnSync(candidate.command, [...candidate.args, "-c", versionScript], {
+    encoding: "utf8",
+  });
+
+  if (result.error) {
+    return { ok: false, reason: "missing", display: candidate.display };
+  }
+
+  if (typeof result.status !== "number" || result.status !== 0) {
+    return {
+      ok: false,
+      reason: "missing",
+      display: candidate.display,
+      stderr: (result.stderr || "").trim(),
+    };
+  }
+
+  const version = parseVersion(result.stdout);
+  if (!version) {
+    return {
+      ok: false,
+      reason: "missing",
+      display: candidate.display,
+      stderr: "Could not parse Python version output.",
+    };
+  }
+
+  if (!meetsMinimum(version, MIN_PYTHON)) {
+    return {
+      ok: false,
+      reason: "version",
+      command: candidate.command,
+      args: candidate.args,
+      display: candidate.display,
+      version,
+    };
+  }
+
+  return {
+    ok: true,
+    command: candidate.command,
+    args: candidate.args,
+    display: candidate.display,
+    version,
+  };
+}
+
+function parseVersion(output) {
+  const trimmed = (output || "").trim();
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(trimmed);
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    raw: trimmed,
+  };
+}
+
+function meetsMinimum(version, minimum) {
+  if (version.major !== minimum.major) {
+    return version.major > minimum.major;
+  }
+  return version.minor >= minimum.minor;
+}
+
+function printPythonError(result) {
+  console.error(
+    `skill-automation-package: Python ${MIN_PYTHON.major}.${MIN_PYTHON.minor}+ is required to run the installer.`,
+  );
+
+  if (result.reason === "version") {
+    for (const candidate of result.unsuitable) {
+      console.error(`- Found ${candidate.display} (${candidate.version.raw}), but it is too old.`);
+    }
+    console.error(
+      "Install Python 3.10 or newer, or make a compatible `python3` or `python` available on PATH, then rerun the install command.",
+    );
+    return;
+  }
+
+  console.error(
+    "No supported Python launcher was found on PATH. Looked for `python3`, `python`, and on Windows `py -3`.",
+  );
+  console.error(
+    "Install Python 3.10 or newer, or update your PATH so one of those commands is available, then rerun the install command.",
+  );
+}
+
+main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "skill-automation-package",
+  "version": "0.2.0",
+  "description": "Portable repo-local skill automation bundle for Codex and Claude Code.",
+  "bin": {
+    "skill-automation-package": "bin/skill-automation-package.js"
+  },
+  "files": [
+    "bin/skill-automation-package.js",
+    "scripts/install.py",
+    "scripts/package_layout.py",
+    "assets/.claude/tools/skill_agent.py",
+    "assets/.claude/skills/project-skill-router/",
+    "assets/.claude/tests/test_skill_agent.py",
+    "templates/agents_block.md",
+    "templates/claude_block.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p 'test_*.py'",
+    "test:wrapper": "node --test tests/node/wrapper.test.js",
+    "test:assets": "PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s assets/.claude/tests -p 'test_*.py'",
+    "install:dry-run": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/install.py --target /tmp/skill-automation-package-dry-run --dry-run",
+    "sync-assets": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_assets.py",
+    "release:check": "npm run test && npm run test:assets && npm run test:wrapper && npm run install:dry-run && npm pack --dry-run --cache /tmp/skill-automation-package-npm-cache"
+  },
+  "managed_assets": [
+    ".claude/tools/skill_agent.py",
+    ".claude/skills/project-skill-router"
+  ],
+  "optional_assets": [
+    ".claude/tests/test_skill_agent.py"
+  ],
+  "executable_assets": [
+    ".claude/tools/skill_agent.py"
+  ],
+  "license": "MIT"
+}

package/scripts/install.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+try:
+    from datetime import UTC
+except ImportError:
+    from datetime import timezone
+
+    UTC = timezone.utc
+
+from package_layout import (
+    ASSETS_ROOT,
+    PACKAGE_MANIFEST,
+    PackageLayout,
+    TEMPLATES_ROOT,
+    copy_assets,
+    load_package_layout,
+)
+
+AGENTS_MARKERS = (
+    "<!-- SKILL-AUTOMATION:AGENTS:START -->",
+    "<!-- SKILL-AUTOMATION:AGENTS:END -->",
+)
+
+CLAUDE_MARKERS = (
+    "<!-- SKILL-AUTOMATION:CLAUDE:START -->",
+    "<!-- SKILL-AUTOMATION:CLAUDE:END -->",
+)
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    layout = load_package_layout(PACKAGE_MANIFEST)
+
+    target = args.target.resolve()
+    if not args.dry_run:
+        target.mkdir(parents=True, exist_ok=True)
+
+    selected_assets = layout.selected_assets(include_optional=not args.no_tests)
+    copied_files = copy_assets(
+        source_root=ASSETS_ROOT,
+        destination_root=target,
+        asset_paths=selected_assets,
+        executable_assets=layout.executable_assets,
+        dry_run=args.dry_run,
+    )
+    wrote_agents = False
+    wrote_claude = False
+
+    if not args.skip_agents:
+        wrote_agents = install_managed_block(
+            target_file=target / "AGENTS.md",
+            template_path=TEMPLATES_ROOT / "agents_block.md",
+            markers=AGENTS_MARKERS,
+            title="# AGENTS.md\n\n",
+            dry_run=args.dry_run,
+        )
+
+    if not args.skip_claude:
+        wrote_claude = install_managed_block(
+            target_file=target / "CLAUDE.md",
+            template_path=TEMPLATES_ROOT / "claude_block.md",
+            markers=CLAUDE_MARKERS,
+            title="# CLAUDE.md\n\n",
+            dry_run=args.dry_run,
+        )
+
+    manifest_path = target / ".claude" / "skill-automation-package.json"
+    wrote_manifest = write_install_manifest(
+        manifest_path=manifest_path,
+        layout=layout,
+        target_root=target,
+        copied_files=copied_files,
+        dry_run=args.dry_run,
+    )
+
+    refreshed = False
+    if not args.dry_run:
+        refresh_registry(target)
+        refreshed = True
+
+    agents_label = "Would update AGENTS.md" if args.dry_run else "Updated AGENTS.md"
+    claude_label = "Would update CLAUDE.md" if args.dry_run else "Updated CLAUDE.md"
+    manifest_label = "Would write install manifest" if args.dry_run else "Wrote install manifest"
+    print(f"Installed skill automation package {layout.version} into {target}")
+    print(f"Copied files: {len(copied_files)}")
+    print(f"{agents_label}: {'yes' if wrote_agents else 'no'}")
+    print(f"{claude_label}: {'yes' if wrote_claude else 'no'}")
+    print(f"{manifest_label}: {'yes' if wrote_manifest else 'no'}")
+    print(f"Refreshed registry: {'yes' if refreshed else 'no'}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Install the repo-local skill automation bundle into another directory."
+    )
+    parser.add_argument(
+        "--target",
+        type=Path,
+        required=True,
+        help="Target repository or directory that should receive the automation bundle.",
+    )
+    parser.add_argument(
+        "--no-tests",
+        action="store_true",
+        help="Do not install the packaged verification test.",
+    )
+    parser.add_argument(
+        "--skip-agents",
+        action="store_true",
+        help="Do not create or update AGENTS.md.",
+    )
+    parser.add_argument(
+        "--skip-claude",
+        action="store_true",
+        help="Do not create or update CLAUDE.md.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview the installation without writing files.",
+    )
+    return parser
+
+
+def install_managed_block(
+    *,
+    target_file: Path,
+    template_path: Path,
+    markers: tuple[str, str],
+    title: str,
+    dry_run: bool,
+) -> bool:
+    block = template_path.read_text(encoding="utf-8").strip() + "\n"
+    start_marker, end_marker = markers
+    existing = target_file.read_text(encoding="utf-8") if target_file.exists() else ""
+    updated = upsert_block(existing, block, start_marker, end_marker, title)
+
+    if not dry_run:
+        target_file.parent.mkdir(parents=True, exist_ok=True)
+        target_file.write_text(updated, encoding="utf-8")
+    return updated != existing
+
+
+def upsert_block(
+    existing: str,
+    block: str,
+    start_marker: str,
+    end_marker: str,
+    title: str,
+) -> str:
+    if not existing.strip():
+        return f"{title}{block}"
+
+    start_index = existing.find(start_marker)
+    end_index = existing.find(end_marker)
+    if start_index != -1 and end_index != -1 and end_index >= start_index:
+        end_index += len(end_marker)
+        replacement = block.rstrip()
+        return (existing[:start_index] + replacement + existing[end_index:]).rstrip() + "\n"
+
+    base = existing.rstrip() + "\n\n"
+    return base + block
+
+
+def write_install_manifest(
+    *,
+    manifest_path: Path,
+    layout: PackageLayout,
+    target_root: Path,
+    copied_files: list[Path],
+    dry_run: bool,
+) -> bool:
+    payload = {
+        "name": layout.name,
+        "version": layout.version,
+        "installed_at": datetime.now(UTC).replace(microsecond=0).isoformat(),
+        "assets": [str(path.relative_to(target_root)) for path in copied_files],
+    }
+    if dry_run:
+        return False
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return True
+
+
+def refresh_registry(target: Path) -> None:
+    subprocess.run(
+        [sys.executable, str(target / ".claude" / "tools" / "skill_agent.py"), "refresh"],
+        check=True,
+        cwd=target,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())