relmio 0.2.0

package/docs/troubleshooting.md

@@ -0,0 +1,193 @@
+# Troubleshooting
+
+Start with the exact symptom you see. Do not delete or rebuild n8n while
+troubleshooting this sidecar. Do not remove an already working manual OAuth
+sidecar until the wizard-managed endpoint has passed a real n8n request.
+
+Always keep a current export or backup of your n8n workflows before using the
+wizard or any manual VPS command. The documented commands are sidecar-only and
+do not delete, restart, or rebuild n8n, but they still access your VPS and write
+files there.
+
+## Confirm the local package first
+
+Run these commands on your own computer, not on the VPS:
+
+```bash
+node --version
+npm view relmio version
+```
+
+Node must be version 22 or newer. Then close every old wizard terminal and
+browser tab and start the newest published build:
+
+```bash
+npx --yes --ignore-scripts relmio@latest
+```
+
+Keep the terminal open. If the browser does not open automatically, copy the
+newest printed `http://127.0.0.1:...` URL into the browser. That URL contains a
+temporary setup token: do not post it in an issue or screenshot.
+
+You do not need to sign in to npm, configure npm 2FA, or own this package to
+run its public `npx` command. npm authentication is required only for the
+maintainer who publishes a release.
+
+## Quick VPS checks
+
+On the VPS:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  ps
+```
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  logs --tail=50 openai-oauth
+```
+
+Check whether Docker published the sidecar port:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  port openai-oauth 10531
+```
+
+Success is no output. `10531/tcp` shown in `docker ps` without a host address
+is only an internal container port. A value such as `0.0.0.0:10531` or
+`127.0.0.1:10531` is a real host mapping and must be investigated rather than
+bypassed.
+
+## Symptom table
+
+| Symptom | Meaning | Fix |
+|---|---|---|
+| `node: command not found`, `node is not recognized`, or Node is older than 22 | The local runtime is missing or unsupported. | Install Node.js 22 or newer on the local computer, open a new terminal, and rerun the `@latest` command. Do not install it on the VPS for the wizard. |
+| The browser did not open | The automatic browser launch failed, but the local server may still be running. | Keep the newest terminal open and copy its newest `127.0.0.1` setup URL into the browser. Do not reuse a URL from a closed terminal. |
+| An old wizard page reports an invalid or expired setup session | The local server was closed or a newer wizard run created a different one-time session token. | Close the old page and use only the URL printed by the currently running terminal. |
+| `npx` appears to run an older wizard | An old terminal or tab is still active, or the package was run without an explicit tag. | Close old runs, check `npm view relmio version`, then run `npx --yes --ignore-scripts relmio@latest`. |
+| `This sign-in request expired` | The OAuth tab is old or the five-minute callback window ended. | Close the old tab and select **Refresh ChatGPT sign-in** from the newest active wizard. |
+| An **OpenAI OAuth** extension page says the sign-in request expired | A browser extension intercepted the `localhost:1455` callback that belongs to the wizard's fresh login. | Temporarily disable the **Sign in with ChatGPT** or **OpenAI OAuth** extension, then select **Refresh ChatGPT sign-in** in the wizard. Re-enable the extension afterward if you still use it elsewhere. |
+| `ChatGPT sign-in did not finish` appears immediately when refreshing an existing credential | Wizard versions through `0.1.3` attempted to reuse `~/.codex/auth.json`, but the bridge CLI requires an interactive terminal before replacing that file. | Update to `0.1.4` or newer. The wizard signs in through its own new credential file and leaves the Codex app credential untouched. |
+| The wizard keeps showing `Waiting for browser sign-in` after approval | Older versions waited for the OAuth helper process to close even after its credential file was ready. | Update to `0.1.5` or newer. Confirm the new **Credential updated** time appears before continuing. |
+| **Credential updated** still shows the old time | The callback reached an old/expired tab, was intercepted, or a different wizard session is open. | Close every old OAuth and wizard tab. Keep one current wizard open, select **Refresh ChatGPT sign-in**, and complete only the newly opened page. |
+| The fresh login cannot bind `localhost:1455` or reports the address is in use | Another OAuth helper or extension process already owns the local callback port. | Close other OAuth login tools and stale wizard processes, then retry. On macOS/Linux, inspect without killing anything using `lsof -nP -iTCP:1455 -sTCP:LISTEN`. |
+| `SSH connection failed. Check the address, password, firewall, and confirmed fingerprint.` | The TCP connection, password authentication, or confirmed host identity did not succeed. | Copy the full address and port from the provider, confirm root password login is enabled, check the provider firewall, rescan and compare the fingerprint, then test `ssh -p 22 root@YOUR_VPS_IP` from the same computer. |
+| The VPS accepts only an SSH key or passkey | The current wizard supports live password authentication, not SSH keys. | Use the manual installation path or a provider-approved password-authenticated administrator account. Do not weaken SSH security or upload a private key into the wizard. |
+| The SSH fingerprint changed | The server was rebuilt, its host keys changed, or the connection may be reaching a different host. | Stop. Verify the address and the new fingerprint through the VPS provider console before confirming it. Never bypass the comparison. |
+| The wizard cannot find n8n | No running container matches the supported n8n image discovery. | Run `docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'` on the VPS. Start or repair n8n through its own deployment process; do not make the wizard recreate it. |
+| No shared Docker network is listed | n8n is not attached to a usable user-defined network. | Inspect n8n's networks and choose one the sidecar can join. Do not publish port `10531` as a workaround. |
+| Safety check says the sidecar published a host port even though Docker shows only `10531/tcp` | Older checks could interpret Docker Compose's internal-only `PublishedPort: 0` marker as a host binding. | Update to `0.1.4` or newer. The wizard now reads the full publisher metadata and still rejects any real host binding. |
+| Safety check reports a real host binding such as `0.0.0.0:10531` | A manual or altered Compose configuration published the port. The latest wizard attempts to stop and remove only its sidecar project before reporting the failure. | Do not bypass the safety check. Confirm the sidecar project is down with the commands above, remove the `ports:` mapping from that sidecar only, and redeploy it without touching n8n. If cleanup could not be confirmed, stop and inspect `/docker/n8n-openai-oauth` before retrying. |
+| `zsh: no matches found: root@**...**` | The hidden-IP asterisks were copied literally. | Use the real IP with no asterisks: `root@YOUR_VPS_IP`. |
+| SSH appears frozen while typing a password | Terminals intentionally show no password characters. | Type the password carefully and press Return. Do not test by typing random visible text. |
+| SSH appears to do nothing | The IP may be incomplete, port 22 may be blocked, or SSH is waiting. | Copy the complete IP from Hostinger. Wait up to 15 seconds, then press Control+C and retry. |
+| `No such file or directory` after local `chown` | A VPS path was used in the local Terminal. | SSH into the VPS first, then run `chown` there. |
+| `No auth file was found at /home/node/.codex/auth.json` | The file is missing, copied to the wrong directory, or the parent directory blocks user `node`. | Verify the mount, owner, and modes using the commands below. |
+| `unknown instruction: "--host"` | The Dockerfile `CMD` JSON was split across Dockerfile instructions. | Replace it with the exact one-line `CMD` from the manual guide. |
+| n8n credential says it cannot connect with `127.0.0.1` | `127.0.0.1` inside n8n is the n8n container, not the sidecar. | Use `http://n8n-openai-oauth:10531/v1`. |
+| Logs show `ENOENT` for `/home/node/.local` | An older wizard release used a read-only root filesystem without a writable app-data directory. | Update to the latest wizard and run the approved install again. It safely refreshes a wizard-managed sidecar. |
+| Network command prints `proxy` | That is the network name, not an empty result. | Select or enter `proxy`. |
+| Logs show repeated “No auth file” and later show “endpoint ready” | `docker compose logs` contains old and new entries. | Read the newest lines at the bottom. The final “endpoint ready” state wins. |
+| n8n requires an API key | The n8n credential UI requires a non-empty value even though the bridge does not. | Enter `local-only`; it is a placeholder, not an OpenAI key. |
+| n8n reports `ECONNREFUSED`, `ENOTFOUND`, or “Couldn’t connect” | The Base URL is wrong, the sidecar is unhealthy, or n8n and the sidecar do not share a network. | Use exactly `http://n8n-openai-oauth:10531/v1`, inspect both container networks, and check the sidecar health/logs. |
+| Models do not appear in n8n | Credential test, network, auth, or model compatibility may be failing. | Verify `/v1/models` inside the sidecar, then retry the n8n credential. |
+| Responses API request fails but models work | The n8n node or bridge version may be incompatible. | Confirm the project is pinned to `openai-oauth@2.0.0`. Try a basic `/v1/responses` request; use chat completions only as a compatibility fallback. |
+| Wizard refuses the install directory | `/docker/n8n-openai-oauth` exists without the wizard marker. | Nothing was overwritten. Move the old directory to a backup name or finish the manual installation; do not delete it blindly. |
+| A manually created `openai-oauth` container already works | It usually does not block the wizard because the wizard uses a separate project, directory, and collision-resistant hostname. | Keep the working deployment until the new endpoint passes a test. If an exact directory, project, container, or network alias collides, move or rename only the old sidecar after backing it up; never remove n8n. |
+
+## Check the OAuth file safely
+
+Do not run `cat` on the file. Check only its metadata:
+
+```bash
+ls -ldn /docker/n8n-openai-oauth/auth
+ls -ln /docker/n8n-openai-oauth/auth/auth.json
+```
+
+Expected:
+
+```text
+auth directory: owner 1000, group 1000, mode drwx------
+auth.json: owner 1000, group 1000, mode -rw-------
+```
+
+Fix on the VPS:
+
+```bash
+chown 1000:1000 /docker/n8n-openai-oauth/auth
+chmod 700 /docker/n8n-openai-oauth/auth
+chown 1000:1000 /docker/n8n-openai-oauth/auth/auth.json
+chmod 600 /docker/n8n-openai-oauth/auth/auth.json
+```
+
+## Check the mount
+
+```bash
+docker inspect n8n-openai-oauth-openai-oauth-1 \
+  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
+```
+
+Expected:
+
+```text
+/docker/n8n-openai-oauth/auth -> /home/node/.codex
+```
+
+The generated container name can differ. Find it with:
+
+```bash
+docker compose \
+  --project-name n8n-openai-oauth \
+  --file /docker/n8n-openai-oauth/docker-compose.yml \
+  ps
+```
+
+## Check the shared network
+
+```bash
+docker inspect n8n-n8n-1 \
+  --format '{{range $name, $_ := .NetworkSettings.Networks}}{{println $name}}{{end}}'
+```
+
+```bash
+docker inspect n8n-openai-oauth-openai-oauth-1 \
+  --format '{{range $name, $_ := .NetworkSettings.Networks}}{{println $name}}{{end}}'
+```
+
+At least one name must match. For the Hostinger setup used during development,
+that name was `proxy`.
+
+## Check from n8n without installing curl
+
+Do not modify the n8n image merely to add a diagnostic tool. Use Node if it is
+available in the n8n container:
+
+```bash
+docker exec n8n-n8n-1 \
+  node -e 'fetch("http://n8n-openai-oauth:10531/v1/models").then(async (response) => { console.log(response.status); console.log(await response.text()); }).catch((error) => { console.error(error.message); process.exit(1); })'
+```
+
+This is a read-only diagnostic request; it does not install anything or
+restart n8n.
+
+## Responses API setting
+
+On OpenAI Chat Model node version 1.3, leave **Use Responses API** on. Earlier
+node versions do not show that switch and use Chat Completions by default.
+Upstream supports both `/v1/responses` and `/v1/chat/completions`. Turn the
+switch off only as a temporary compatibility test if:
+
+- `/v1/models` works;
+- the node is definitely calling the correct Base URL; and
+- the error specifically concerns `/v1/responses`.
+
+If chat completions work but Responses does not, record the n8n version, node
+version, bridge logs, and sanitized error before changing anything else.

package/docs/video-outline.md

@@ -0,0 +1,152 @@
+# YouTube walkthrough outline
+
+This outline explains the project without overstating what the unofficial
+OAuth bridge provides. Adjust the timing to match your recording.
+
+## Suggested title
+
+> Relmio: connect self-hosted n8n to a private OpenAI-compatible OAuth sidecar
+
+Avoid titles that promise a free API key, unlimited usage, or guaranteed
+credits. This project does not create an OpenAI Platform API key.
+
+## Seven-minute structure
+
+### 0:00 — The problem
+
+- n8n's OpenAI credential expects an API key and supports a custom Base URL.
+- You already have a self-hosted n8n Docker deployment.
+- You want a private, experimental bridge without editing or restarting n8n.
+
+On screen: the README warning and the final architecture diagram.
+
+### 0:40 — The safety promise
+
+- The wizard runs on the user's own computer.
+- It creates a second Docker Compose project.
+- It never edits the n8n Compose file or image.
+- It never publishes sidecar port `10531`.
+- It requires an SSH fingerprint check and final plan approval.
+
+On screen: the **Sidecar-only guarantee** and Step 4 review screen.
+
+### 1:30 — Why the design works
+
+Use this simple explanation:
+
+> n8n sends an OpenAI-shaped request to a private Docker hostname. The
+> sidecar translates that request into the upstream OAuth-authenticated flow
+> and returns an OpenAI-compatible response. Docker networking keeps the
+> endpoint between containers instead of publishing it on the internet.
+
+On screen: the Mermaid flowchart in the README.
+
+### 2:20 — Start the npm package
+
+Run locally:
+
+```bash
+npx --yes --ignore-scripts relmio@latest
+```
+
+Explain that:
+
+- `npx` downloads and runs the published version for this session;
+- the wizard binds to `127.0.0.1`;
+- the printed setup URL is private and temporary;
+- the terminal must remain open until the wizard finishes.
+
+### 2:55 — Sign in and verify freshness
+
+- Complete the newest ChatGPT sign-in page.
+- Temporarily disable an OAuth browser extension only if it intercepts the
+  `localhost:1455` callback.
+- Show the **Credential updated** timestamp.
+- Explain that the wizard uses
+  `~/.n8n-openai-oauth/auth.json`, not `~/.codex/auth.json`.
+
+Never show the auth file, browser session URL, cookies, or account details.
+
+### 3:40 — Connect to the VPS safely
+
+- Enter the complete address and SSH port.
+- Check the SHA-256 fingerprint before the password field unlocks.
+- Explain that the password is used only for the live SSH connection and is
+  not saved.
+
+Blur or replace the real address, fingerprint, username, and provider account
+details in the recording.
+
+### 4:25 — Detect n8n and approve the plan
+
+- Select the running n8n container.
+- Select the network shared with the sidecar.
+- Read the **will** and **will not** columns.
+- Approve the exact plan.
+
+Emphasize that discovery is read-only and remote writes begin only after
+approval.
+
+### 5:15 — Configure n8n
+
+Use:
+
+```text
+API Key: local-only
+Organization ID: leave empty
+Base URL: http://n8n-openai-oauth:10531/v1
+Add Custom Header: off
+```
+
+Then add an OpenAI Chat Model to the AI Agent or Basic LLM Chain. For Chat
+Model node version 1.3, keep **Use Responses API** on. If the switch is absent,
+use the earlier node version's default Chat Completions behavior. Test one
+simple prompt before adding tools. The model list depends on the signed-in
+account and may change.
+
+### 6:10 — Refresh and troubleshoot
+
+- Run the same `@latest` command to refresh a session or update the
+  wizard-managed sidecar.
+- If n8n cannot connect, check the shared network and exact Base URL.
+- If sign-in expires, close the old tab and begin again from the active
+  wizard.
+- If SSH fails, verify the address, port, firewall, password, and fingerprint.
+
+Point viewers to [Troubleshooting](troubleshooting.md).
+
+### 6:45 — Close with the limitations
+
+- This is unofficial and experimental.
+- It does not create an OpenAI Platform API key.
+- ChatGPT and OpenAI API billing are separate products.
+- Eligibility, models, and rate limits can change.
+- Users must protect the OAuth credential and follow current terms.
+
+## Recording safety checklist
+
+- Use a disposable or sanitized demo VPS.
+- Use a reserved documentation address such as `192.0.2.10` in mock screens.
+- Hide browser address bars containing wizard session tokens.
+- Never open or print `auth.json`.
+- Never record an SSH password, private key, cookie, passkey prompt, or 2FA
+  code.
+- Blur real fingerprints, hostnames, account email addresses, and workflow
+  data.
+- Confirm that port `10531` has no host mapping.
+- Show the version used in the recording:
+
+  ```bash
+  npm view relmio version
+  ```
+
+## Reference links for the description
+
+- [`openai-oauth` v2.0.0](https://github.com/EvanZhouDev/openai-oauth/releases/tag/v2.0.0)
+- [n8n OpenAI credential documentation](https://docs.n8n.io/integrations/builtin/credentials/openai/)
+- [Docker Compose networking](https://docs.docker.com/compose/how-tos/networking/)
+- [OpenAI: using Codex with a ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)
+- [OpenAI Terms of Use](https://openai.com/policies/terms-of-use/)
+
+Add the final video URL to the README only after the video is published. Do
+not invent or reuse an unrelated tutorial link.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "relmio",
+  "version": "0.2.0",
+  "description": "Turn a supported ChatGPT/Codex OAuth sign-in into a private OpenAI-compatible endpoint, starting with self-hosted n8n.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Demonbane18/n8n-openai-oauth-setup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Demonbane18/n8n-openai-oauth-setup/issues"
+  },
+  "homepage": "https://github.com/Demonbane18/n8n-openai-oauth-setup#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "npm@10.9.8",
+  "bin": {
+    "relmio": "src/cli.js",
+    "planrelay": "src/cli.js",
+    "n8n-openai-oauth-setup": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "docs",
+    "README.md",
+    "SPEC.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "preview": "node scripts/preview.js",
+    "package:build": "node scripts/build-npm-package.js",
+    "test": "node --test",
+    "lint": "node scripts/check-syntax.js",
+    "release:check": "node scripts/check-release-metadata.js",
+    "check": "npm run lint && npm run release:check && npm test"
+  },
+  "dependencies": {
+    "ssh2": "1.17.0"
+  }
+}

package/scripts/build-npm-package.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import {
+  copyFile,
+  cp,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+const sourceRoot = fileURLToPath(new URL("..", import.meta.url));
+const defaultOutputDirectory = join(sourceRoot, "dist", "npm");
+
+async function copyPublishEntry({ entry, stagingDirectory }) {
+  const source = join(sourceRoot, entry);
+  const target = join(stagingDirectory, entry);
+
+  if (entry === "README.md") {
+    await copyFile(join(sourceRoot, "npm", "README.md"), target);
+    return;
+  }
+
+  await cp(source, target, { recursive: true });
+}
+
+export async function stageNpmPackage(stagingDirectory) {
+  const packageJson = JSON.parse(
+    await readFile(join(sourceRoot, "package.json"), "utf8"),
+  );
+  const publishEntries = new Set([
+    "package.json",
+    ...(packageJson.files ?? []),
+  ]);
+
+  await mkdir(stagingDirectory, { recursive: true });
+  for (const entry of publishEntries) {
+    await copyPublishEntry({ entry, stagingDirectory });
+  }
+
+  return packageJson;
+}
+
+export async function buildNpmPackage({
+  outputDirectory = defaultOutputDirectory,
+} = {}) {
+  const stagingDirectory = await mkdtemp(join(tmpdir(), "relmio-package-"));
+
+  try {
+    const packageJson = await stageNpmPackage(stagingDirectory);
+    await mkdir(outputDirectory, { recursive: true });
+
+    const expectedFilename = `${packageJson.name}-${packageJson.version}.tgz`;
+    const expectedPath = join(outputDirectory, expectedFilename);
+    await rm(expectedPath, { force: true });
+
+    const { stdout } = await execFileAsync(
+      npmCommand,
+      [
+        "pack",
+        stagingDirectory,
+        "--json",
+        "--ignore-scripts",
+        "--pack-destination",
+        outputDirectory,
+      ],
+      {
+        cwd: sourceRoot,
+        env: {
+          ...process.env,
+          npm_config_cache: join(stagingDirectory, ".npm-cache"),
+        },
+      },
+    );
+    const [packedPackage] = JSON.parse(stdout);
+    const tarballPath = resolve(outputDirectory, packedPackage.filename);
+
+    if (basename(tarballPath) !== expectedFilename) {
+      throw new Error(
+        `npm produced ${basename(tarballPath)} instead of ${expectedFilename}.`,
+      );
+    }
+
+    return { packageJson, packedPackage, tarballPath };
+  } finally {
+    await rm(stagingDirectory, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  const outputArgument = process.argv[2];
+  const outputDirectory =
+    outputArgument === undefined
+      ? defaultOutputDirectory
+      : resolve(process.cwd(), outputArgument);
+  const result = await buildNpmPackage({ outputDirectory });
+  console.log(result.tarballPath);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/check-release-metadata.js

@@ -0,0 +1,100 @@
+import { access, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const RELEASE_HEADING = /^## \[([^\]]+)\] - \d{4}-\d{2}-\d{2}$/mu;
+const SEMVER =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*)|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:(?:0|[1-9]\d*)|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+
+export function validateReleaseMetadata({
+  packageJson,
+  packageLock,
+  changelog,
+  tag,
+  requirePackageLock = true,
+}) {
+  const version = packageJson?.version;
+  if (typeof version !== "string" || !SEMVER.test(version)) {
+    throw new Error("package.json must contain a valid semantic version.");
+  }
+
+  if (packageLock || requirePackageLock) {
+    if (packageLock?.version !== version) {
+      throw new Error(
+        `package-lock.json version ${packageLock?.version ?? "missing"} does not match ${version}.`,
+      );
+    }
+    if (packageLock?.packages?.[""]?.version !== version) {
+      throw new Error(
+        `package-lock.json root package version ${packageLock?.packages?.[""]?.version ?? "missing"} does not match ${version}.`,
+      );
+    }
+  }
+
+  const changelogVersion = changelog.match(RELEASE_HEADING)?.[1];
+  if (changelogVersion !== version) {
+    throw new Error(
+      `newest CHANGELOG.md version ${changelogVersion ?? "missing"} does not match ${version}.`,
+    );
+  }
+
+  if (tag && tag !== `v${version}`) {
+    throw new Error(`release tag ${tag} does not match v${version}.`);
+  }
+
+  return { version };
+}
+
+async function readOptionalFile(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function main() {
+  const [packageJsonContents, packageLockContents, changelog, isGitCheckout] =
+    await Promise.all([
+      readFile("package.json", "utf8"),
+      readOptionalFile("package-lock.json"),
+      readFile("CHANGELOG.md", "utf8"),
+      pathExists(".git"),
+    ]);
+  const tag =
+    process.env.GITHUB_REF_TYPE === "tag"
+      ? process.env.GITHUB_REF_NAME
+      : undefined;
+  const result = validateReleaseMetadata({
+    packageJson: JSON.parse(packageJsonContents),
+    packageLock:
+      packageLockContents === undefined
+        ? undefined
+        : JSON.parse(packageLockContents),
+    changelog,
+    tag,
+    requirePackageLock: isGitCheckout,
+  });
+  console.log(`Release metadata is synchronized at v${result.version}.`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/check-syntax.js

@@ -0,0 +1,59 @@
+import { readdir } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { spawn } from "node:child_process";
+
+const roots = ["src", "test", "scripts"];
+
+async function collectJavaScriptFiles(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectJavaScriptFiles(path)));
+    } else if (extname(entry.name) === ".js") {
+      files.push(path);
+    }
+  }
+
+  return files;
+}
+
+function checkFile(path) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ["--check", path], {
+      stdio: "inherit",
+    });
+
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Syntax check failed for ${path}`));
+      }
+    });
+  });
+}
+
+const files = (
+  await Promise.all(
+    roots.map(async (root) => {
+      try {
+        return await collectJavaScriptFiles(root);
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          return [];
+        }
+        throw error;
+      }
+    }),
+  )
+).flat();
+
+for (const file of files) {
+  await checkFile(file);
+}
+
+console.log(`Syntax checked ${files.length} JavaScript files.`);