@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/create-version/github-workflow.js

@@ -0,0 +1,199 @@
+/**
+ * Adapts GitHub CLI for credential preflight and dispatch reconciliation.
+ * @module create-version/github-workflow
+ */
+
+import {
+  CI_DIAGNOSTIC_LIMIT, CI_DISPATCH_STATUS, CI_FAILURE_CODE, CI_GITHUB_TOKEN_VARIABLES, CI_ORGANIZATION_BINDING_PAGE_SIZE,
+  CI_ORGANIZATION_BINDING_RESOURCE, CI_RELEASE_RUN_TITLE_PREFIX, CI_RUN_LOOKUP_LIMIT,
+} from "../constants/ci-release.js";
+import { ciWorkflowPath } from "./ci-config.js";
+import { GITHUB_REPOSITORY_PATTERN, MAIN_BRANCH, RELEASE_REMOTE, REMOTE_MAIN_REF } from "../constants/create-version.js";
+import { CiReleaseError } from "./errors.js";
+import { runCaptured } from "./process.js";
+
+/**
+ * @typedef {{ version: string, tag: string, sha: string }} CiReleaseIdentity
+ * @typedef {{ status: "submitted" | "existing", url: string | null }} CiDispatchResult
+ * @typedef {"secret" | "variable"} ActionsBindingKind
+ * @typedef {{
+ *   preflight: (workflow: string, secrets: string[], variables: string[]) => Promise<void>,
+ *   dispatch: (workflow: string, release: CiReleaseIdentity, retryCommand: string) => Promise<CiDispatchResult>,
+ * }} GithubWorkflowClient
+ */
+
+/**
+ * Builds the `run-name` the generated workflow gives a dispatched release, which identifies its runs.
+ * @param {CiReleaseIdentity} release - Dispatched release.
+ * @returns {string} Run title, such as `astra-rp release v1.2.4 <sha>`.
+ */
+export function formatCiReleaseRunTitle(release) {
+  return `${CI_RELEASE_RUN_TITLE_PREFIX} ${release.tag} ${release.sha}`;
+}
+
+/**
+ * Redacts inherited GitHub credentials and bounds external command diagnostics.
+ * @param {string} diagnostic - GitHub CLI diagnostic.
+ * @returns {string} Safe terminal diagnostic.
+ */
+function safeDiagnostic(diagnostic) {
+  return CI_GITHUB_TOKEN_VARIABLES.reduce((output, name) => process.env[name] ? output.replaceAll(/** @type {string} */ (process.env[name]), "[redactado]") : output, diagnostic).slice(0, CI_DIAGNOSTIC_LIMIT);
+}
+
+/**
+ * Builds the repository-level commands that would configure the missing bindings.
+ * @param {ActionsBindingKind} kind - Actions binding kind.
+ * @param {string[]} names - Missing binding names.
+ * @param {string} repository - `owner/name` repository.
+ * @returns {string} Commands joined for a terminal hint.
+ */
+function repositorySetCommands(kind, names, repository) {
+  return names.map((name) => `gh ${kind} set ${name} --repo ${repository}`).join("; ");
+}
+
+/**
+ * Creates a GitHub workflow adapter with an explicit subprocess boundary.
+ * @param {string} repositoryRoot - Checkout whose origin selects the repository.
+ * @param {typeof runCaptured} [capture] - Process executor, injectable by other CLI hosts.
+ * @returns {GithubWorkflowClient} Preflight and dispatch operations.
+ */
+export function createGithubWorkflowClient(repositoryRoot, capture = runCaptured) {
+  let repository = "";
+
+  /** @param {string[]} args - GitHub CLI arguments. @returns {ReturnType<typeof runCaptured>} Captured result. */
+  const github = (args) => capture("gh", args, { cwd: repositoryRoot });
+
+  /**
+   * Lists matching accepted runs before a dispatch is repeated.
+   * @param {string} workflow - Workflow filename.
+   * @param {CiReleaseIdentity} release - Existing immutable release.
+   * @param {string} retryCommand - Recovery command preserving the tag.
+   * @returns {Promise<{ status: string, conclusion: string | null, url: string } | null>} Existing active or successful run.
+   */
+  async function findAcceptedRun(workflow, release, retryCommand) {
+    const result = await github(["run", "list", "--repo", repository, "--workflow", workflow, "--event", "workflow_dispatch", "--limit", String(CI_RUN_LOOKUP_LIMIT), "--json", "displayTitle,status,conclusion,url"]);
+    if (result.status !== 0) throw new CiReleaseError(CI_FAILURE_CODE.lookup, `No se pudo verificar si ${release.tag} ya tiene una ejecución de ${workflow}: ${safeDiagnostic(result.stderr)}`, `No se envió otra ejecución. Revisá Actions y retomá con ${retryCommand} cuando se pueda consultar el estado.`);
+    const runs = JSON.parse(result.stdout);
+    return runs.find((/** @type {{ displayTitle: string, status: string, conclusion: string | null }} */ run) => run.displayTitle === formatCiReleaseRunTitle(release) && (run.status !== "completed" || run.conclusion === "success")) ?? null;
+  }
+
+  /**
+   * Lists organization bindings of one kind that GitHub shares with the repository, honoring their visibility.
+   * @param {ActionsBindingKind} kind - Actions binding kind.
+   * @param {string} workflow - Workflow to be dispatched, for diagnostics.
+   * @param {string[]} missing - Names absent at repository level, for diagnostics.
+   * @returns {Promise<string[]>} Binding names available to the repository through its organization.
+   * @throws {CiReleaseError} When organization bindings cannot be listed; the missing names stay unverified.
+   */
+  async function listOrganizationBindings(kind, workflow, missing) {
+    const resource = CI_ORGANIZATION_BINDING_RESOURCE[kind];
+    const result = await github(["api", "--paginate", `repos/${repository}/actions/${resource.path}?per_page=${CI_ORGANIZATION_BINDING_PAGE_SIZE}`, "--jq", `.${resource.collection}[].name`]);
+    if (result.status !== 0) throw new CiReleaseError(CI_FAILURE_CODE.preflight, `Faltan ${kind}s de Actions para ${workflow} a nivel repositorio (${missing.join(", ")}) y no se pudieron verificar los ${kind}s de organización compartidos con ${repository}: ${safeDiagnostic(result.stderr)}`, `Dale a gh permiso para leer los ${kind}s de Actions de ${repository} o configurá ${repositorySetCommands(kind, missing, repository)}; no se tocó la versión.`);
+    return result.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+  }
+
+  /**
+   * Tells whether a revision of the checkout contains a file.
+   * @param {string} revision - Ref such as `refs/tags/v1.2.0`.
+   * @param {string} filePath - Root-relative path.
+   * @returns {Promise<boolean>} True when `git cat-file -e` finds the file at that revision.
+   */
+  async function hasFileAt(revision, filePath) {
+    return (await capture("git", ["cat-file", "-e", `${revision}:${filePath}`], { cwd: repositoryRoot })).status === 0;
+  }
+
+  /**
+   * Requires the release tag to contain the workflow, since dispatching with `--ref <tag>` runs the
+   * definition stored in that tag instead of whatever `main` holds today.
+   * @param {string} workflow - Workflow filename.
+   * @param {CiReleaseIdentity} release - Existing immutable release.
+   * @param {string} retryCommand - Recovery command preserving the tag.
+   * @returns {Promise<void>} Resolves when the tag carries the workflow.
+   * @throws {CiReleaseError} When the tag has no such workflow; nothing is dispatched.
+   */
+  async function assertWorkflowInReleaseTag(workflow, release, retryCommand) {
+    const workflowPath = ciWorkflowPath(workflow);
+    if (!(await hasFileAt(`refs/tags/${release.tag}`, workflowPath))) throw new CiReleaseError(CI_FAILURE_CODE.preflight, `${release.tag} no contiene ${workflowPath}; el release solo se ejecuta con el workflow de su propio tag, no con el de ${MAIN_BRANCH}.`, `No se envió ninguna ejecución. Publicá ${release.tag} con --local, o traé el tag con git fetch ${RELEASE_REMOTE} tag ${release.tag} si falta localmente y volvé a correr ${retryCommand}.`);
+  }
+
+  /**
+   * Requires the workflow file to exist on the default branch as well: GitHub only triggers
+   * `workflow_dispatch` for workflows present on the default branch, even when `--ref <tag>` selects
+   * the definition stored in the tag, so a workflow renamed or deleted on `main` after the release can
+   * no longer be dispatched under its old name. Reads `origin/main` as last fetched by the release flow.
+   * @param {string} workflow - Workflow filename.
+   * @param {CiReleaseIdentity} release - Existing immutable release.
+   * @param {string} retryCommand - Recovery command preserving the tag.
+   * @returns {Promise<void>} Resolves when the default branch carries the workflow.
+   * @throws {CiReleaseError} When the default branch has no such workflow; nothing is dispatched.
+   */
+  async function assertWorkflowOnDefaultBranch(workflow, release, retryCommand) {
+    const workflowPath = ciWorkflowPath(workflow);
+    if (!(await hasFileAt(`refs/remotes/${REMOTE_MAIN_REF}`, workflowPath))) throw new CiReleaseError(CI_FAILURE_CODE.preflight, `${REMOTE_MAIN_REF} no contiene ${workflowPath}: GitHub solo dispara workflow_dispatch para workflows que existen en la rama por defecto (${MAIN_BRANCH}), aunque ${release.tag} conserve el suyo.`, `No se envió ninguna ejecución. Restaurá ${workflowPath} con ese nombre en ${MAIN_BRANCH} y volvé a correr ${retryCommand}, o publicá ${release.tag} con --local.`);
+  }
+
+  return {
+    /**
+     * Checks GitHub CLI, authentication, default branch and configured worker credentials.
+     * @param {string} workflow - Workflow to be dispatched.
+     * @param {string[]} secrets - Secret names required by the worker, at repository or shared organization level.
+     * @param {string[]} variables - Variable names required by the worker, at repository or shared organization level.
+     * @returns {Promise<void>} Resolves before any bump when dispatch prerequisites are available.
+     * @throws {CiReleaseError} When a prerequisite is missing or cannot be checked.
+     */
+    async preflight(workflow, secrets, variables) {
+      const origin = await capture("git", ["remote", "get-url", RELEASE_REMOTE], { cwd: repositoryRoot });
+      repository = GITHUB_REPOSITORY_PATTERN.exec(origin.stdout)?.[1] ?? "";
+      if (!repository) throw new CiReleaseError(CI_FAILURE_CODE.preflight, "El modo CI requiere un origin de GitHub.", "Configurá el remoto de GitHub o elegí --local; no se tocó la versión.");
+      const installed = await github(["--version"]);
+      if (installed.status !== 0) throw new CiReleaseError(CI_FAILURE_CODE.preflight, "No se pudo ejecutar GitHub CLI (gh).", "Instalá gh y ejecutá gh auth login, o elegí --local.");
+      const authenticated = await github(["auth", "status", "--hostname", "github.com"]);
+      if (authenticated.status !== 0) throw new CiReleaseError(CI_FAILURE_CODE.preflight, `gh no está autenticado para disparar ${workflow}.`, "Ejecutá gh auth login con acceso al repo; no se tocó la versión.");
+      const metadata = await github(["repo", "view", repository, "--json", "defaultBranchRef,isInOrganization"]);
+      if (metadata.status !== 0) throw new CiReleaseError(CI_FAILURE_CODE.preflight, `No se pudo consultar ${repository}: ${safeDiagnostic(metadata.stderr)}`, "Verificá el acceso del usuario de gh al repo.");
+      const repositoryMetadata = JSON.parse(metadata.stdout);
+      if (repositoryMetadata.defaultBranchRef?.name !== MAIN_BRANCH) throw new CiReleaseError(CI_FAILURE_CODE.preflight, "workflow_dispatch requiere que el workflow exista en la rama por defecto, que en este flujo debe ser main.", "Usá main como rama por defecto o ejecutá el release con --local.");
+      const ownedByOrganization = repositoryMetadata.isInOrganization === true;
+      for (const [kind, required] of /** @type {[ActionsBindingKind, string[]][]} */ ([["secret", secrets], ["variable", variables]])) {
+        if (required.length === 0) continue;
+        const listed = await github([kind, "list", "--repo", repository, "--json", "name"]);
+        if (listed.status !== 0) throw new CiReleaseError(CI_FAILURE_CODE.preflight, `No se pudieron verificar los ${kind}s de CI en ${repository}.`, `Revisá los permisos de gh y los ${kind}s de Actions; no se tocó la versión.`);
+        const available = JSON.parse(listed.stdout).map((/** @type {{ name: string }} */ entry) => entry.name);
+        let missing = required.filter((name) => !available.includes(name));
+        if (missing.length > 0 && ownedByOrganization) {
+          const shared = await listOrganizationBindings(kind, workflow, missing);
+          missing = missing.filter((name) => !shared.includes(name));
+        }
+        if (missing.length > 0) {
+          const organizationHint = ownedByOrganization ? ` o compartí el ${kind} de organización con ${repository}` : "";
+          throw new CiReleaseError(CI_FAILURE_CODE.preflight, `Faltan ${kind}s de Actions para ${workflow}: ${missing.join(", ")}.`, `Configurá ${repositorySetCommands(kind, missing, repository)}${organizationHint} y volvé a correr el comando.`);
+        }
+      }
+    },
+
+    /**
+     * Submits the exact pushed tag pinned to the workflow version stored in that tag (`--ref <tag>`), so a
+     * retry never runs a newer workflow from `main` against the older tagged checkout; reconciles a failed
+     * response without automatic resubmission.
+     * @param {string} workflow - Workflow filename.
+     * @param {CiReleaseIdentity} release - Version, tag and commit already on origin.
+     * @param {string} retryCommand - Explicit retry command that never creates another bump.
+     * @returns {Promise<CiDispatchResult>} Submission state, never a claim that publication finished.
+     * @throws {CiReleaseError} When acceptance cannot be confirmed.
+     */
+    async dispatch(workflow, release, retryCommand) {
+      const existing = await findAcceptedRun(workflow, release, retryCommand);
+      if (existing) return { status: CI_DISPATCH_STATUS.existing, url: existing.url };
+      await assertWorkflowInReleaseTag(workflow, release, retryCommand);
+      await assertWorkflowOnDefaultBranch(workflow, release, retryCommand);
+      const dispatched = await github(["workflow", "run", workflow, "--repo", repository, "--ref", release.tag, "-f", `version=${release.version}`, "-f", `tag=${release.tag}`, "-f", `sha=${release.sha}`]);
+      if (dispatched.status !== 0) {
+        let accepted = null;
+        try { accepted = await findAcceptedRun(workflow, release, retryCommand); } catch { /* The original dispatch remains unconfirmed; do not repeat it. */ }
+        if (accepted) return { status: CI_DISPATCH_STATUS.existing, url: accepted.url };
+        throw new CiReleaseError(CI_FAILURE_CODE.dispatch, `${release.tag} ya está en origin, pero no se confirmó el inicio de ${workflow}: ${safeDiagnostic(dispatched.stderr)}`, `Revisá Actions antes de reenviar con ${retryCommand}; no hace otro bump ni repite el push.`);
+      }
+      return { status: CI_DISPATCH_STATUS.submitted, url: `https://github.com/${repository}/actions/workflows/${workflow}` };
+    },
+  };
+}

package/src/create-version/index.js

@@ -0,0 +1,54 @@
+/**
+ * `@astra-kit/rp/create-version`: shared release command.
+ *
+ * Projects run it as `astra-rp create-version` and describe their differences
+ * in `astra-rp.config.js` (checks, migrations,
+ * preparation, publication). The pure planner and the state reader are
+ * exported for project tests and custom tooling.
+ *
+ * @module create-version
+ */
+
+/**
+ * @typedef {import("./config.js").CreateVersionConfig} CreateVersionConfig
+ * @typedef {import("./ci-config.js").CiReleaseConfig} CiReleaseConfig
+ */
+
+export {
+  computeNpmIntegrity,
+  computeSha256,
+  expandArtifactPattern,
+  findPnpmPackRewrites,
+  findPreparedArtifact,
+  isSafeArtifactPath,
+  verifyPreparedArtifact,
+  withArtifactOutsidePackageRoot,
+} from "./artifact.js";
+export { defineCreateVersionConfig, loadCreateVersionConfig, resolveCreateVersionConfig } from "./config.js";
+export { CiReleaseError, ReleaseStepError } from "./errors.js";
+export { resolveCiReleaseConfig } from "./ci-config.js";
+export {
+  buildNpmAuthConfigLine,
+  buildNpmOwnerListArguments,
+  buildNpmPublishArguments,
+  buildNpmPublishEnvironment,
+  buildNpmTokenEnvironment,
+  buildNpmViewArguments,
+  buildNpmWhoamiArguments,
+  checkNpmPublishAccess,
+  lookupPublishedVersions,
+  parseNpmOwnerList,
+  parseNpmPackDryRunOutput,
+  publishToNpm,
+  readNpmPackIntegrity,
+  resolveNpmToken,
+  resolvePublishRegistry,
+  withNpmAuthConfig,
+} from "./npm.js";
+export { describeNpmAuthProblem, describeNpmPublishFailure, describeNpmTokenSource } from "./npm-auth.js";
+export { DEFAULT_CAPABILITIES, RELEASE_USAGE, buildReleasePlan, describeFeatureBranchGaps, parseReleaseArguments } from "./plan.js";
+export { createGitReader, listCommits, parseCommitLog, readPackageManifestAt, readPackageVersionAt, runCaptured, runCommandLine, runInherited } from "./process.js";
+export { createHookContext, runCreateVersion } from "./run.js";
+export { collectReleaseState, findLastRelease, readChangelogState } from "./state.js";
+export { isRegistryProvider, resolvePublicationOptions } from "./registry-config.js";
+export { checkRegistryAccess, lookupRegistryVersions, resolveRegistry, selectProjectRegistry } from "./registry.js";

package/src/create-version/json.js

@@ -0,0 +1,32 @@
+/**
+ * JSON helpers shared by the release modes: plain-object checks and manifest reads.
+ *
+ * @module create-version/json
+ */
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { PACKAGE_MANIFEST_FILE } from "../constants/create-version.js";
+
+/**
+ * Tells whether a value is a plain JSON object.
+ *
+ * @param {unknown} value - Any value.
+ * @returns {value is Record<string, unknown>} Whether it is a non-array object.
+ */
+export function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Reads and parses a JSON manifest from the working tree; read and parse errors propagate as they are.
+ *
+ * @param {string} directory - Directory the manifest path is relative to.
+ * @param {string} [manifestPath] - Manifest path; the `package.json` of the directory by default.
+ * @returns {any} Parsed manifest.
+ * @throws {Error} When the file cannot be read or is not valid JSON.
+ */
+export function readJsonManifest(directory, manifestPath = PACKAGE_MANIFEST_FILE) {
+  return JSON.parse(readFileSync(path.join(directory, manifestPath), "utf8"));
+}

package/src/create-version/jsonc.js

@@ -0,0 +1,76 @@
+/**
+ * Parses native registry JSONC manifests while preserving character offsets for version-only edits.
+ *
+ * @module create-version/jsonc
+ */
+
+import { isRecord } from "./json.js";
+
+/**
+ * Replaces comments and trailing commas with whitespace, without touching string values or offsets.
+ *
+ * @param {string} content - JSON or JSONC text.
+ * @returns {string} JSON text with the same length and line breaks.
+ * @throws {Error} When a block comment is unterminated.
+ */
+export function normalizeJsonc(content) {
+  const characters = content.split("");
+  let quoted = false;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  if (characters[0] === "\uFEFF") characters[0] = " ";
+  for (let index = 0; index < characters.length; index += 1) {
+    const character = characters[index];
+    const next = characters[index + 1];
+    if (lineComment || blockComment) {
+      if (blockComment && character === "*" && next === "/") {
+        characters[index] = characters[index + 1] = " ";
+        blockComment = false;
+        index += 1;
+      } else if (character === "\n" || character === "\r") {
+        lineComment = false;
+      } else characters[index] = " ";
+    } else if (quoted) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') quoted = false;
+    } else if (character === '"') quoted = true;
+    else if (character === "/" && (next === "/" || next === "*")) {
+      lineComment = next === "/";
+      blockComment = next === "*";
+      characters[index] = characters[index + 1] = " ";
+      index += 1;
+    }
+  }
+  if (blockComment) throw new Error("Unterminated JSONC block comment");
+  quoted = false;
+  escaped = false;
+  for (let index = 0; index < characters.length; index += 1) {
+    const character = characters[index];
+    if (quoted) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') quoted = false;
+    } else if (character === '"') quoted = true;
+    else if (character === ",") {
+      let following = index + 1;
+      while (/\s/u.test(characters[following] ?? "") && following < characters.length) following += 1;
+      if (characters[following] === "]" || characters[following] === "}") characters[index] = " ";
+    }
+  }
+  return characters.join("");
+}
+
+/**
+ * Reads a native JSONC manifest as JSON, preserving comments in the caller's source text.
+ *
+ * @param {string} content - JSONC manifest text.
+ * @returns {Record<string, unknown>} Parsed manifest.
+ * @throws {Error} When the manifest is not an object or is malformed.
+ */
+export function parseJsoncManifest(content) {
+  const parsed = JSON.parse(normalizeJsonc(content));
+  if (!isRecord(parsed)) throw new Error("Registry manifest must be a JSON object");
+  return parsed;
+}

package/src/create-version/jsr.js

@@ -0,0 +1,96 @@
+/**
+ * Reads and versions native JSR manifests, then publishes with the official JSR or Deno client.
+ *
+ * @module create-version/jsr
+ */
+
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_NPM_REGISTRY_URL, PACKAGE_VERSION_FIELD_PATTERN, UNSAFE_QUOTED_PATH_PATTERN } from "../constants/create-version.js";
+import { JSR_CHILD_TOKEN_VARIABLE, JSR_CONFIG_FILES, JSR_NPM_CLIENT_SPEC, JSR_PACKAGE_NAME_PATTERN, JSR_SHELL_SAFE_TOKEN_PATTERN } from "../constants/registry.js";
+import { ReleaseStepError } from "./errors.js";
+import { normalizeJsonc, parseJsoncManifest } from "./jsonc.js";
+import { quoteShellArguments, runRedactedInherited, USES_SHELL_FOR_PACKAGE_MANAGERS } from "./process.js";
+import { buildNpmPublishEnvironment } from "./npm.js";
+import { STRICT_UTF8_DECODER } from "./strict-utf8.js";
+
+/**
+ * Finds the native JSR manifest inside a package and reads only its publication metadata.
+ *
+ * @param {string} packageRoot - Package directory.
+ * @param {string | null} configFile - Explicit package-relative path, or auto-detection.
+ * @returns {{ filePath: string, originalBytes: Buffer, text: string, manifest: Record<string, unknown>, packageName: string }} Native manifest.
+ * @throws {Error} When the file is absent, linked outside the package, malformed or unscoped.
+ */
+export function readJsrManifest(packageRoot, configFile = null) {
+  const filePath = configFile ?? JSR_CONFIG_FILES.find((candidate) => existsSync(path.join(packageRoot, candidate)));
+  if (!filePath) throw new Error("JSR requiere jsr.json, jsr.jsonc, deno.json o deno.jsonc dentro del paquete");
+  const absolutePath = path.join(packageRoot, filePath);
+  const relativeRealPath = path.relative(realpathSync(packageRoot), realpathSync(absolutePath));
+  if (!lstatSync(absolutePath).isFile() || relativeRealPath.split(path.sep).includes("..") || path.isAbsolute(relativeRealPath)) {
+    throw new Error(`${filePath} debe ser un archivo regular dentro del paquete`);
+  }
+  const originalBytes = readFileSync(absolutePath);
+  const text = STRICT_UTF8_DECODER.decode(originalBytes);
+  const manifest = parseJsoncManifest(text);
+  const packageName = manifest.name;
+  if (typeof packageName !== "string" || !JSR_PACKAGE_NAME_PATTERN.test(packageName)) {
+    throw new Error(`${filePath} debe declarar un nombre JSR con scope (@scope/package)`);
+  }
+  return { filePath: filePath.replaceAll("\\", "/"), originalBytes, text, manifest, packageName };
+}
+
+/**
+ * Prepares a native manifest version edit for the same transaction as package.json; never writes it.
+ *
+ * @param {{ repositoryRoot: string, reader: import("./process.js").GitReader, commands: import("../package-manager.js").ProjectCommands, config?: { versionFiles: string[] } }} context - Release context.
+ * @param {string} packageRoot - Package checkout directory.
+ * @param {import("./registry-config.js").ResolvedPublicationOptions} options - Native publication options.
+ * @param {string} version - New stable version.
+ * @returns {Promise<import("./run.js").ReleaseFileUpdate[]>} Transactional native manifest update.
+ * @throws {ReleaseStepError} When the manifest is dirty, untracked or lacks a usable top-level version.
+ */
+export async function prepareJsrVersionUpdates(context, packageRoot, options, version) {
+  const native = readJsrManifest(packageRoot, options.configFile);
+  const filePath = path.relative(context.repositoryRoot, path.join(packageRoot, native.filePath)).replaceAll("\\", "/");
+  if (context.config?.versionFiles.includes(filePath)) throw new ReleaseStepError(`${filePath} ya sincroniza su versión como manifest JSR.`, "Sacalo de versionFiles para que una sola operación gestione su versión; no se escribió nada.");
+  const pathspec = `:(literal)${filePath}`;
+  const tracked = await context.reader.git(["ls-files", "-z", "--", pathspec]);
+  const changed = await context.reader.git(["diff", "--name-only", "HEAD", "--", pathspec]);
+  if (!tracked.split("\0").includes(filePath) || changed) {
+    throw new ReleaseStepError(`${filePath} debe estar trackeado y sin cambios antes de versionar JSR.`, `Commiteá el manifest y volvé a correr ${context.commands.createVersion}; no se tocó la versión.`);
+  }
+  const normalized = normalizeJsonc(native.text);
+  const match = PACKAGE_VERSION_FIELD_PATTERN.exec(normalized);
+  if (!match) throw new ReleaseStepError(`${filePath} no tiene un campo version para sincronizar.`, "Declaralo en el manifest JSR antes de crear el release.");
+  const start = match.index + match[1].length;
+  const end = match.index + match[0].length - match[2].length;
+  const content = `${native.text.slice(0, start)}${version}${native.text.slice(end)}`;
+  if (parseJsoncManifest(content).version !== version) {
+    throw new ReleaseStepError(`${filePath} tiene una versión anidada antes de la versión principal.`, "Mové version al nivel principal antes de los objetos anidados; no se escribió nada.");
+  }
+  return [{ filePath, originalBytes: native.originalBytes, content }];
+}
+
+/**
+ * Publishes with a pinned official client and a selected config; the token is never printed by astra-rp.
+ *
+ * @param {string} packageRoot - Release checkout.
+ * @param {{ registryUrl: string, options: import("./registry-config.js").ResolvedPublicationOptions }} registry - Selected native registry.
+ * @param {string | null} token - Personal token, or `null` for browser/OIDC authentication.
+ * @param {ReturnType<typeof readJsrManifest>} [native] - Native manifest of the package, when the caller already read it.
+ * @returns {Promise<number>} Official client exit code.
+ * @throws {Error} When a shell operand or token cannot be passed safely.
+ */
+export async function publishToJsr(packageRoot, registry, token, native = readJsrManifest(packageRoot, registry.options.configFile)) {
+  const command = registry.options.jsrClient === "deno" ? "deno" : "npx";
+  const prefix = registry.options.jsrClient === "deno" ? [] : ["--yes", `--registry=${DEFAULT_NPM_REGISTRY_URL}`, JSR_NPM_CLIENT_SPEC];
+  const args = [...prefix, "publish", "--config", native.filePath];
+  if (args.some((argument) => UNSAFE_QUOTED_PATH_PATTERN.test(argument))) throw new Error("JSR: un argumento del cliente no es seguro para el shell");
+  if (token && !JSR_SHELL_SAFE_TOKEN_PATTERN.test(token)) throw new Error("JSR: el token no se puede pasar de forma segura al cliente");
+  const env = { ...buildNpmPublishEnvironment(), JSR_URL: registry.registryUrl, DEBUG: "", ...(token ? { [JSR_CHILD_TOKEN_VARIABLE]: token } : {}) };
+  if (USES_SHELL_FOR_PACKAGE_MANAGERS) {
+    return runRedactedInherited(`${command} ${quoteShellArguments(args)}${token ? ` --token "%${JSR_CHILD_TOKEN_VARIABLE}%"` : ""}`, [], { cwd: packageRoot, shell: true, env }, token ? [token] : []);
+  }
+  return runRedactedInherited(command, [...args, ...(token ? ["--token", token] : [])], { cwd: packageRoot, env }, token ? [token] : []);
+}

package/src/create-version/local-changes.js

@@ -0,0 +1,178 @@
+/**
+ * Local changes of `astra-rp create-version --ignore-local-changes`: the
+ * uncommitted changes (staged, unstaged and untracked) are set aside in a
+ * `git stash` entry while the release runs, so checks, preparation and
+ * publication only see the release commit, and are restored at the end.
+ *
+ * The restore is exact or nothing: staged changes go back to the index only,
+ * unstaged changes to the working tree only and untracked files stay
+ * untracked. Every layer is checked before anything is written; when one does
+ * not apply cleanly on top of the release, nothing is touched and the stash
+ * entry is kept.
+ *
+ * @module create-version/local-changes
+ */
+
+import { existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { CHANGELOG_FILE } from "../constants/changelog.js";
+import { LOCAL_CHANGES_STASH_MESSAGE } from "../constants/create-version.js";
+import { DEFAULT_PROJECT_COMMANDS } from "../package-manager.js";
+import { ReleaseStepError } from "./errors.js";
+
+/**
+ * @typedef {import("./process.js").GitReader} GitReader
+ * @typedef {{ sha: string, keptPaths: string[] }} SetAsideChanges
+ *   Stash entry holding the changes, identified by its commit so a later stash does not shift it;
+ *   `keptPaths` stayed in the working tree (the release commits them: its `CHANGELOG.md` files).
+ * @typedef {{ restored: true } | { restored: false, reason: string }} LocalChangesRestore
+ */
+
+/** Stash references are `stash@{<index>}`; the index shifts when other entries are pushed. */
+const STASH_REFERENCE_PREFIX = "stash@";
+
+/** Prefix of the temporary directory holding the patches of a restore. */
+const RESTORE_DIRECTORY_PREFIX = "astra-rp-local-changes-";
+
+/**
+ * Builds the pathspec of the set-aside changes: the kept files are left out, because a stash made
+ * with a pathspec still records them in its index and tree.
+ *
+ * @param {readonly string[]} keptPaths - Files that stayed in the working tree, relative to the root.
+ * @returns {string[]} Pathspec arguments, after `--`.
+ */
+function buildPathspec(keptPaths) {
+  return [".", ...keptPaths.map((keptPath) => `:(exclude,literal)${keptPath}`)];
+}
+
+/**
+ * Sets the uncommitted changes aside in a new stash entry.
+ *
+ * @param {GitReader} reader - Git reader of the repository root.
+ * @param {{ keepChangelog?: boolean, keptPaths?: readonly string[], createVersionCommand?: string }} options - Files
+ *   that stay in the working tree because a new release commits them (`keepChangelog` keeps the root
+ *   `CHANGELOG.md`; a monorepo passes every released package's `keptPaths`), and how the project
+ *   runs create-version (for the hints).
+ * @returns {Promise<SetAsideChanges>} Stash entry holding the changes.
+ * @throws {ReleaseStepError} When Git cannot create the stash entry; nothing was changed then.
+ */
+export async function setAsideLocalChanges(reader, { keepChangelog = false, keptPaths: configuredKeptPaths, createVersionCommand = DEFAULT_PROJECT_COMMANDS.createVersion }) {
+  const keptPaths = [...(configuredKeptPaths ?? (keepChangelog ? [CHANGELOG_FILE] : []))];
+  if ((await reader.tryGit(["stash", "push", "--include-untracked", "--message", LOCAL_CHANGES_STASH_MESSAGE, "--", ...buildPathspec(keptPaths)])) === null) {
+    throw new ReleaseStepError("No se pudieron apartar los cambios sin commitear (git stash push falló).", `No se tocó nada: revisá git status y volvé a correr ${createVersionCommand}.`);
+  }
+
+  const sha = await reader.tryGit(["rev-parse", "--verify", "--quiet", `${STASH_REFERENCE_PREFIX}{0}`]);
+
+  if (!sha) {
+    throw new ReleaseStepError("Se apartaron los cambios pero no se encontró la entrada de git stash.", `Buscalos con git stash list y recuperalos con git stash pop --index antes de volver a correr ${createVersionCommand}.`);
+  }
+
+  return { sha, keptPaths };
+}
+
+/**
+ * Writes the diff between two revisions of the set-aside paths to a patch file.
+ *
+ * @param {GitReader} reader - Git reader of the repository root.
+ * @param {string} from - Revision the patch starts from.
+ * @param {string} to - Revision the patch leads to.
+ * @param {string[]} pathspec - Paths included in the patch.
+ * @param {string} patchPath - File the patch is written to.
+ * @returns {Promise<boolean | null>} `true` with changes, `false` when empty, `null` when Git failed.
+ */
+async function writePatch(reader, from, to, pathspec, patchPath) {
+  // `--output` keeps the exact bytes of the patch; `--no-ext-diff` and `--no-textconv` keep it appliable.
+  if ((await reader.tryGit(["diff", "--binary", "--full-index", "--no-ext-diff", "--no-textconv", "--no-color", `--output=${patchPath}`, from, to, "--", ...pathspec])) === null) {
+    return null;
+  }
+
+  return existsSync(patchPath) && statSync(patchPath).size > 0;
+}
+
+/**
+ * Lists the untracked files the stash entry holds (its third parent), if any.
+ *
+ * @param {GitReader} reader - Git reader of the repository root.
+ * @param {string} sha - Stash commit.
+ * @returns {Promise<string[] | null>} Paths relative to the root, or `null` when Git failed.
+ */
+async function listStashedUntrackedFiles(reader, sha) {
+  if ((await reader.tryGit(["rev-parse", "--verify", "--quiet", `${sha}^3`])) === null) {
+    return [];
+  }
+
+  const output = await reader.tryGit(["ls-tree", "-r", "-z", "--name-only", `${sha}^3`]);
+  return output === null ? null : output.split("\0").filter(Boolean);
+}
+
+/**
+ * Restores the changes set aside by {@link setAsideLocalChanges} exactly as they were: staged
+ * changes staged, unstaged changes unstaged and untracked files untracked. Nothing is written
+ * unless every layer applies cleanly; the stash entry is dropped only after a full restore.
+ *
+ * @param {GitReader} reader - Git reader of the repository root.
+ * @param {string} repositoryRoot - Repository root.
+ * @param {SetAsideChanges} setAside - Stash entry returned by {@link setAsideLocalChanges}.
+ * @returns {Promise<LocalChangesRestore>} Whether the changes are back, and why not otherwise.
+ */
+export async function restoreLocalChanges(reader, repositoryRoot, setAside) {
+  const { sha, keptPaths } = setAside;
+  const stashShas = ((await reader.tryGit(["stash", "list", "--format=%H"])) ?? "").split("\n").map((line) => line.trim());
+  const stashIndex = stashShas.indexOf(sha);
+
+  if (stashIndex === -1) {
+    return { restored: false, reason: `la entrada ${sha} ya no está en git stash list` };
+  }
+
+  const stashReference = `${STASH_REFERENCE_PREFIX}{${stashIndex}}`;
+  const keptReason = (/** @type {string} */ detail) => ({ restored: /** @type {const} */ (false), reason: `${detail}; no se tocó nada y siguen en ${stashReference}` });
+  const pathspec = buildPathspec(keptPaths);
+  const patchDirectory = mkdtempSync(path.join(os.tmpdir(), RESTORE_DIRECTORY_PREFIX));
+  const stagedPatch = path.join(patchDirectory, "staged.patch");
+  const workingTreePatch = path.join(patchDirectory, "working-tree.patch");
+
+  try {
+    // Staged layer: stash base -> stash index, applied to the index only. Working tree layer:
+    // stash base -> stash tree (staged plus unstaged), applied to the working tree only.
+    const hasStaged = await writePatch(reader, `${sha}^1`, `${sha}^2`, pathspec, stagedPatch);
+    const hasWorkingTree = await writePatch(reader, `${sha}^1`, sha, pathspec, workingTreePatch);
+    const untrackedFiles = await listStashedUntrackedFiles(reader, sha);
+
+    if (hasStaged === null || hasWorkingTree === null || untrackedFiles === null) {
+      return keptReason("Git no pudo leer la entrada de stash");
+    }
+
+    if (hasStaged && (await reader.tryGit(["apply", "--check", "--cached", stagedPatch])) === null) {
+      return keptReason("los cambios staged chocan con lo que cambió el release en el índice");
+    }
+
+    if (hasWorkingTree && (await reader.tryGit(["apply", "--check", workingTreePatch])) === null) {
+      return keptReason("los cambios del working tree chocan con lo que cambió el release");
+    }
+
+    const occupiedFile = untrackedFiles.find((file) => existsSync(path.join(repositoryRoot, file)));
+    if (occupiedFile) {
+      return keptReason(`el archivo sin trackear ${occupiedFile} ya existe después del release`);
+    }
+
+    if (hasStaged && (await reader.tryGit(["apply", "--cached", stagedPatch])) === null) {
+      return keptReason("git apply --cached falló después de validar");
+    }
+
+    if (hasWorkingTree && (await reader.tryGit(["apply", workingTreePatch])) === null) {
+      return { restored: false, reason: `los cambios staged volvieron pero git apply del working tree falló; el resto sigue en ${stashReference}` };
+    }
+
+    if (untrackedFiles.length > 0 && (await reader.tryGit(["restore", `--source=${sha}^3`, "--worktree", "--", ...untrackedFiles.map((file) => `:(literal)${file}`)])) === null) {
+      return { restored: false, reason: `volvieron los cambios trackeados pero no los archivos sin trackear; siguen en ${stashReference}` };
+    }
+
+    await reader.tryGit(["stash", "drop", "--quiet", stashReference]);
+    return { restored: true };
+  } finally {
+    rmSync(patchDirectory, { recursive: true, force: true });
+  }
+}