@follenfang/fupload 0.0.0-bootstrap.0 → 0.0.2

package/npm/lib/skill-installer.mjs

@@ -0,0 +1,228 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const INSTALL_STAMP = ".fupload-npm-install.json";
+export const INSTALL_STAMP_SCHEMA = "fupload.npm-skill-install.v1";
+const LOCK_STALE_MS = 5 * 60 * 1000;
+const LOCK_WAIT_MS = 15 * 1000;
+const TEXT_EXTENSIONS = new Set([".json", ".md", ".py", ".txt", ".yaml", ".yml"]);
+
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function canonicalContent(filename, content) {
+  if (!TEXT_EXTENSIONS.has(path.extname(filename).toLowerCase())) {
+    return content;
+  }
+  return Buffer.from(content.toString("utf8").replaceAll("\r\n", "\n"), "utf8");
+}
+
+function readJson(filename) {
+  return JSON.parse(fs.readFileSync(filename, "utf8"));
+}
+
+function writeJson(filename, value) {
+  fs.writeFileSync(filename, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
+function normalizedFiles(root, current = root) {
+  if (!fs.existsSync(current)) {
+    return [];
+  }
+  const result = [];
+  for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+    if (
+      entry.name === INSTALL_STAMP ||
+      entry.name === "tests" ||
+      entry.name === "__pycache__" ||
+      entry.name === ".pytest_cache" ||
+      entry.name.endsWith(".pyc")
+    ) {
+      continue;
+    }
+    const absolute = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...normalizedFiles(root, absolute));
+    } else if (entry.isFile()) {
+      result.push(path.relative(root, absolute).split(path.sep).join("/"));
+    }
+  }
+  return result.sort((left, right) => left.localeCompare(right));
+}
+
+export function loadDistribution(packageRoot) {
+  const packageRecord = readJson(path.join(packageRoot, "package.json"));
+  const manifest = readJson(path.join(packageRoot, "npm", "skill-manifest.json"));
+  if (
+    manifest.schema !== "fupload.npm-skill-manifest.v1" ||
+    manifest.package_name !== packageRecord.name ||
+    manifest.package_version !== packageRecord.version ||
+    manifest.skill_version !== packageRecord.version
+  ) {
+    throw new Error("The packaged Skill manifest does not match package.json.");
+  }
+  return { packageRecord, manifest, sourceSkill: path.join(packageRoot, "fupload") };
+}
+
+export function verifySkill(root, manifest) {
+  const expected = manifest.files.map((entry) => entry.path);
+  const actual = normalizedFiles(root);
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    return { valid: false, reason: "file_inventory_mismatch" };
+  }
+  for (const entry of manifest.files) {
+    const absolute = path.join(root, ...entry.path.split("/"));
+    try {
+      const content = canonicalContent(absolute, fs.readFileSync(absolute));
+      if (content.length !== entry.bytes || sha256(content) !== entry.sha256) {
+        return { valid: false, reason: "file_hash_mismatch", path: entry.path };
+      }
+    } catch {
+      return { valid: false, reason: "file_missing", path: entry.path };
+    }
+  }
+  return { valid: true, reason: "matched" };
+}
+
+function copyManifestFiles(source, destination, manifest) {
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of manifest.files) {
+    const from = path.join(source, ...entry.path.split("/"));
+    const to = path.join(destination, ...entry.path.split("/"));
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.copyFileSync(from, to);
+  }
+}
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function acquireLock(target) {
+  const lock = `${target}.npm-install.lock`;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const descriptor = fs.openSync(lock, "wx", 0o600);
+      fs.writeFileSync(descriptor, `${JSON.stringify({ pid: process.pid })}\n`);
+      return {
+        release() {
+          fs.closeSync(descriptor);
+          fs.rmSync(lock, { force: true });
+        },
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+          fs.rmSync(lock, { force: true });
+          continue;
+        }
+      } catch (statError) {
+        if (statError.code !== "ENOENT") {
+          throw statError;
+        }
+      }
+      await sleep(50);
+    }
+  }
+  throw new Error(`Timed out waiting for the Skill install lock: ${lock}`);
+}
+
+export function readInstallStamp(target) {
+  try {
+    return readJson(path.join(target, INSTALL_STAMP));
+  } catch {
+    return null;
+  }
+}
+
+function installStamp(distribution, target) {
+  return {
+    schema: INSTALL_STAMP_SCHEMA,
+    package_name: distribution.packageRecord.name,
+    package_version: distribution.packageRecord.version,
+    skill_version: distribution.manifest.skill_version,
+    tree_sha256: distribution.manifest.tree_sha256,
+    target: path.resolve(target),
+    installed_at: new Date().toISOString(),
+  };
+}
+
+export async function ensureSkill({ packageRoot, target }) {
+  const distribution = loadDistribution(packageRoot);
+  const sourceCheck = verifySkill(distribution.sourceSkill, distribution.manifest);
+  if (!sourceCheck.valid) {
+    throw new Error(`The packaged Skill failed validation: ${sourceCheck.reason}.`);
+  }
+  const lock = await acquireLock(target);
+  try {
+    const exists = fs.existsSync(target);
+    const targetCheck = exists
+      ? verifySkill(target, distribution.manifest)
+      : { valid: false, reason: "missing" };
+    const stamp = exists ? readInstallStamp(target) : null;
+    if (targetCheck.valid) {
+      if (!stamp) {
+        writeJson(path.join(target, INSTALL_STAMP), installStamp(distribution, target));
+        return { status: "adopted", target, distribution };
+      }
+      if (stamp.package_name !== distribution.packageRecord.name) {
+        throw new Error(`The Skill target is managed by ${stamp.package_name}.`);
+      }
+      if (stamp.target !== path.resolve(target)) {
+        writeJson(path.join(target, INSTALL_STAMP), installStamp(distribution, target));
+      }
+      return { status: "current", target, distribution };
+    }
+    if (exists && (!stamp || stamp.package_name !== distribution.packageRecord.name)) {
+      throw new Error(`The Skill target already exists and is not a matching managed Fuploader Skill: ${target}`);
+    }
+
+    const parent = path.dirname(target);
+    const nonce = `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
+    const staging = path.join(parent, `.fupload-stage-${nonce}`);
+    const backup = path.join(parent, `.fupload-backup-${nonce}`);
+    let movedOld = false;
+    try {
+      copyManifestFiles(distribution.sourceSkill, staging, distribution.manifest);
+      writeJson(path.join(staging, INSTALL_STAMP), installStamp(distribution, target));
+      const stagingCheck = verifySkill(staging, distribution.manifest);
+      if (!stagingCheck.valid) {
+        throw new Error(`The staged Skill failed validation: ${stagingCheck.reason}.`);
+      }
+      if (exists) {
+        fs.renameSync(target, backup);
+        movedOld = true;
+      }
+      try {
+        fs.renameSync(staging, target);
+      } catch (error) {
+        if (movedOld && !fs.existsSync(target)) {
+          fs.renameSync(backup, target);
+          movedOld = false;
+        }
+        throw error;
+      }
+      if (movedOld) {
+        fs.rmSync(backup, { recursive: true, force: true });
+      }
+      return { status: exists ? "upgraded" : "installed", target, distribution };
+    } finally {
+      fs.rmSync(staging, { recursive: true, force: true });
+      if (movedOld && fs.existsSync(backup) && !fs.existsSync(target)) {
+        fs.renameSync(backup, target);
+      }
+    }
+  } finally {
+    lock.release();
+  }
+}

package/npm/lib/uninstall.mjs

@@ -0,0 +1,211 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { clearManagedInstall, readManagedInstall } from "./managed-install.mjs";
+import { resolveSkillDirectory } from "./options.mjs";
+import { INSTALL_STAMP, INSTALL_STAMP_SCHEMA, readInstallStamp } from "./skill-installer.mjs";
+
+export const PACKAGE_NAME = "@follenfang/fupload";
+
+export class ManagedUninstallError extends Error {
+  constructor(message, details) {
+    super(message);
+    this.name = "ManagedUninstallError";
+    this.code = "FUPLOAD_UNINSTALL_FAILED";
+    this.details = details;
+  }
+}
+
+export function inspectManagedSkill(target) {
+  const resolved = path.resolve(target);
+  if (resolved === path.parse(resolved).root) {
+    return { target: resolved, status: "preserved_unmanaged", reason: "filesystem_root" };
+  }
+  if (!fs.existsSync(resolved)) {
+    return { target: resolved, status: "missing" };
+  }
+  const stamp = readInstallStamp(resolved);
+  if (
+    stamp?.schema !== INSTALL_STAMP_SCHEMA ||
+    stamp?.package_name !== PACKAGE_NAME ||
+    path.resolve(stamp?.target || "") !== resolved
+  ) {
+    return { target: resolved, status: "preserved_unmanaged", reason: "ownership_unknown" };
+  }
+  return { target: resolved, status: "managed", marker: path.join(resolved, INSTALL_STAMP) };
+}
+
+export async function cleanupManagedSkills({
+  platform = process.platform,
+  env = process.env,
+  home = os.homedir(),
+  extraTargets = [],
+  removePath = (target) => fs.rmSync(target, { recursive: true, force: true }),
+} = {}) {
+  const registry = readManagedInstall({ platform, env, home });
+  const targets = [
+    ...new Set([
+      ...registry.targets
+        .filter((entry) => typeof entry?.path === "string")
+        .map((entry) => path.resolve(entry.path)),
+      path.resolve(resolveSkillDirectory({ env, home })),
+      ...extraTargets.map((target) => path.resolve(target)),
+    ]),
+  ];
+  const result = {
+    schema: "fupload.npm-cleanup-result.v1",
+    skills: [],
+    project_data: "preserved",
+    platform_credentials: "preserved",
+    platform_logs: "preserved",
+  };
+  for (const target of targets) {
+    const inspection = inspectManagedSkill(target);
+    if (inspection.status !== "managed") {
+      result.skills.push(inspection);
+      continue;
+    }
+    try {
+      removePath(inspection.target);
+      if (fs.existsSync(inspection.target)) {
+        throw new Error("path still exists after deletion");
+      }
+      result.skills.push({ target: inspection.target, status: "removed" });
+    } catch (error) {
+      result.skills.push({ target: inspection.target, status: "failed" });
+      throw new ManagedUninstallError("A managed Fuploader Skill could not be removed.", {
+        result,
+        object: inspection.target,
+        reason: error.message,
+      });
+    }
+  }
+  clearManagedInstall({ platform, env, home });
+  return result;
+}
+
+export function resolveGlobalInstall(packageRoot, platform = process.platform) {
+  let current = path.resolve(packageRoot);
+  let nodeModules;
+  while (true) {
+    if (path.basename(current).toLowerCase() === "node_modules") {
+      nodeModules = current;
+      break;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  if (!nodeModules) {
+    throw new ManagedUninstallError("The npm installation prefix could not be resolved.", {
+      package_root: path.resolve(packageRoot),
+    });
+  }
+  let prefix = path.dirname(nodeModules);
+  if (platform !== "win32" && path.basename(prefix) === "lib") {
+    prefix = path.dirname(prefix);
+  }
+  const launcher = platform === "win32"
+    ? path.join(prefix, "fupload.cmd")
+    : path.join(prefix, "bin", "fupload");
+  if (!fs.existsSync(launcher)) {
+    throw new ManagedUninstallError("fupload uninstall requires a global npm installation.", {
+      package_root: path.resolve(packageRoot),
+      prefix,
+      launcher,
+    });
+  }
+  return { prefix, launcher, packageRoot: path.resolve(packageRoot) };
+}
+
+export function resolveNpmCli({
+  platform = process.platform,
+  env = process.env,
+  run = spawnSync,
+} = {}) {
+  if (env.npm_execpath && fs.existsSync(env.npm_execpath)) {
+    return path.resolve(env.npm_execpath);
+  }
+  if (platform === "win32") {
+    const located = run("where.exe", ["npm.cmd"], { encoding: "utf8", windowsHide: true });
+    if (located.status === 0) {
+      for (const shim of located.stdout.split(/\r?\n/).filter(Boolean)) {
+        const candidate = path.join(path.dirname(shim.trim()), "node_modules", "npm", "bin", "npm-cli.js");
+        if (fs.existsSync(candidate)) {
+          return candidate;
+        }
+      }
+    }
+  } else {
+    const located = run("which", ["npm"], { encoding: "utf8" });
+    if (located.status === 0) {
+      try {
+        const candidate = fs.realpathSync(located.stdout.trim());
+        if (fs.existsSync(candidate)) {
+          return candidate;
+        }
+      } catch {
+        // Fall through to the stable error below.
+      }
+    }
+  }
+  throw new ManagedUninstallError("npm-cli.js could not be located for self-removal.");
+}
+
+export function runNpmCli(args, { platform = process.platform, env = process.env } = {}) {
+  return spawnSync(process.execPath, [resolveNpmCli({ platform, env }), ...args], {
+    encoding: "utf8", env, shell: false, windowsHide: true,
+  });
+}
+
+function bounded(value) {
+  return String(value || "").trim().slice(0, 4000);
+}
+
+export async function uninstallSelf({
+  packageRoot,
+  target,
+  platform = process.platform,
+  env = process.env,
+  home = os.homedir(),
+  runNpm = runNpmCli,
+} = {}) {
+  const installation = resolveGlobalInstall(packageRoot, platform);
+  const cleanup = await cleanupManagedSkills({
+    platform,
+    env,
+    home,
+    extraTargets: target ? [target] : [],
+  });
+  const args = ["uninstall", "-g", "--ignore-scripts", "--prefix", installation.prefix, PACKAGE_NAME];
+  const npmResult = runNpm(args, { platform, env });
+  if (npmResult.error || npmResult.status !== 0) {
+    throw new ManagedUninstallError("npm could not remove the Fuploader package and CLI.", {
+      cleanup,
+      prefix: installation.prefix,
+      exit_status: npmResult.status,
+      stdout: bounded(npmResult.stdout),
+      stderr: bounded(npmResult.stderr || npmResult.error?.message),
+    });
+  }
+  const residuals = [installation.launcher, installation.packageRoot].filter((candidate) => fs.existsSync(candidate));
+  if (residuals.length) {
+    throw new ManagedUninstallError("npm reported success but Fuploader installation files remain.", {
+      cleanup,
+      prefix: installation.prefix,
+      residuals,
+    });
+  }
+  return {
+    schema: "fupload.npm-uninstall-result.v1",
+    success: true,
+    package: PACKAGE_NAME,
+    prefix: installation.prefix,
+    cleanup,
+    npm_exit_status: npmResult.status,
+  };
+}

package/npm/lib/update.mjs

@@ -0,0 +1,102 @@
+import os from "node:os";
+import path from "node:path";
+
+import { ensureCurseForgeEnv } from "./curseforge-config.mjs";
+import { readManagedInstall, recordManagedSkill } from "./managed-install.mjs";
+import { resolveSkillDirectory } from "./options.mjs";
+import { ensureSkill, loadDistribution } from "./skill-installer.mjs";
+import { PACKAGE_NAME, inspectManagedSkill, resolveGlobalInstall, runNpmCli } from "./uninstall.mjs";
+
+export class ManagedUpdateError extends Error {
+  constructor(message, details) {
+    super(message);
+    this.name = "ManagedUpdateError";
+    this.code = "FUPLOAD_UPDATE_FAILED";
+    this.details = details;
+  }
+}
+
+function bounded(value) {
+  return String(value || "").trim().slice(0, 4000);
+}
+
+export async function updateSelf({
+  packageRoot,
+  target,
+  platform = process.platform,
+  env = process.env,
+  home = os.homedir(),
+  runNpm = runNpmCli,
+} = {}) {
+  const curseforgeConfig = ensureCurseForgeEnv({ home, platform });
+  const installation = resolveGlobalInstall(packageRoot, platform);
+  const current = loadDistribution(packageRoot);
+  const primary = target || resolveSkillDirectory({ env, home });
+  await ensureSkill({ packageRoot, target: primary });
+  recordManagedSkill(primary, { platform, env, home });
+
+  const args = ["install", "-g", "--ignore-scripts", "--prefix", installation.prefix, `${PACKAGE_NAME}@latest`];
+  const npmResult = runNpm(args, { platform, env });
+  if (npmResult.error || npmResult.status !== 0) {
+    throw new ManagedUpdateError("npm could not update the Fuploader package and CLI.", {
+      from_version: current.packageRecord.version,
+      prefix: installation.prefix,
+      exit_status: npmResult.status,
+      stdout: bounded(npmResult.stdout),
+      stderr: bounded(npmResult.stderr || npmResult.error?.message),
+    });
+  }
+
+  let updated;
+  try {
+    updated = loadDistribution(packageRoot);
+  } catch (error) {
+    throw new ManagedUpdateError("The updated Fuploader package failed distribution validation.", {
+      from_version: current.packageRecord.version,
+      prefix: installation.prefix,
+      reason: error.message,
+    });
+  }
+  const registry = readManagedInstall({ platform, env, home });
+  const targets = [
+    ...new Set([
+      ...registry.targets
+        .filter((entry) => typeof entry?.path === "string")
+        .map((entry) => path.resolve(entry.path)),
+      path.resolve(resolveSkillDirectory({ env, home })),
+      path.resolve(primary),
+    ]),
+  ];
+  const skills = [];
+  for (const candidate of targets) {
+    const inspection = inspectManagedSkill(candidate);
+    if (inspection.status === "preserved_unmanaged") {
+      skills.push(inspection);
+      continue;
+    }
+    try {
+      const ensured = await ensureSkill({ packageRoot, target: candidate });
+      recordManagedSkill(candidate, { platform, env, home });
+      skills.push({ target: candidate, status: ensured.status, version: updated.packageRecord.version });
+    } catch (error) {
+      throw new ManagedUpdateError("The npm CLI updated but a managed Fuploader Skill could not be synchronized.", {
+        from_version: current.packageRecord.version,
+        to_version: updated.packageRecord.version,
+        target: candidate,
+        skills,
+        reason: error.message,
+      });
+    }
+  }
+  return {
+    schema: "fupload.npm-update-result.v1",
+    success: true,
+    package: PACKAGE_NAME,
+    prefix: installation.prefix,
+    from_version: current.packageRecord.version,
+    to_version: updated.packageRecord.version,
+    npm_exit_status: npmResult.status,
+    curseforge_config: curseforgeConfig,
+    skills,
+  };
+}

package/npm/lib/versions.mjs

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function readJson(filename) {
+  return JSON.parse(fs.readFileSync(filename, "utf8"));
+}
+
+function matchedVersion(filename, pattern, label) {
+  const source = fs.readFileSync(filename, "utf8");
+  const match = source.match(pattern);
+  if (!match) {
+    throw new Error(`${label} version could not be read from ${filename}.`);
+  }
+  return match[1];
+}
+
+export function readVersions(packageRoot, { includeManifest = true } = {}) {
+  const packageRecord = readJson(path.join(packageRoot, "package.json"));
+  const skillFile = path.join(packageRoot, "fupload", "SKILL.md");
+  const frontmatter = fs.readFileSync(skillFile, "utf8").split(/^---\s*$/m)[1] || "";
+  const skillMatch = frontmatter.match(/^\s*version:\s*["']?([^\s"']+)["']?\s*$/m);
+  if (!skillMatch) {
+    throw new Error(`Skill metadata version could not be read from ${skillFile}.`);
+  }
+  const versions = {
+    package: packageRecord.version,
+    skill: skillMatch[1],
+    python: matchedVersion(
+      path.join(packageRoot, "fupload", "scripts", "fupload_cli", "__init__.py"),
+      /__version__\s*=\s*["']([^"']+)["']/,
+      "Python CLI",
+    ),
+  };
+  const lockFile = path.join(packageRoot, "package-lock.json");
+  if (fs.existsSync(lockFile)) {
+    const lock = readJson(lockFile);
+    versions.lock = lock.version;
+    versions.lockRoot = lock.packages?.[""]?.version;
+  }
+  const manifestFile = path.join(packageRoot, "npm", "skill-manifest.json");
+  if (includeManifest && fs.existsSync(manifestFile)) {
+    const manifest = readJson(manifestFile);
+    versions.manifestPackage = manifest.package_version;
+    versions.manifestSkill = manifest.skill_version;
+  }
+  return versions;
+}
+
+export function assertUnifiedVersions(versions) {
+  const expected = versions.package;
+  const mismatches = Object.entries(versions).filter(([, value]) => value !== expected);
+  if (mismatches.length) {
+    throw new Error(
+      `Version mismatch: expected ${expected}; ${mismatches.map(([name, value]) => `${name}=${value}`).join(", ")}.`,
+    );
+  }
+  return expected;
+}
+
+export function selectedReleaseTag({ env = process.env, argv = process.argv.slice(2) } = {}) {
+  const candidates = [env.GITHUB_REF_NAME, ...argv];
+  return candidates.find((value) => /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value || "")) || "";
+}

package/npm/postinstall.mjs

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ensureCurseForgeEnv } from "./lib/curseforge-config.mjs";
+import { recordManagedSkill } from "./lib/managed-install.mjs";
+import { resolveSkillDirectory } from "./lib/options.mjs";
+import { ensureSkill } from "./lib/skill-installer.mjs";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const target = resolveSkillDirectory();
+
+try {
+  const config = ensureCurseForgeEnv();
+  const result = await ensureSkill({ packageRoot, target });
+  recordManagedSkill(target);
+  process.stdout.write(`Fuploader Skill ${result.status}: ${target}\n`);
+  process.stdout.write(`CurseForge configuration ${config.status}: ${config.path}\n`);
+} catch (error) {
+  process.stderr.write(`Fuploader Skill installation failed: ${error.message}\n`);
+  process.exitCode = 1;
+}