@izykitten/ce 0.0.1 → 0.0.2

package/README.md

@@ -2,16 +2,16 @@
 
 Container engine wrapper for CI: registry login (including Forgejo OIDC), tag and cache rewriting for `docker`, `podman` and `buildah`, and a Docker credential helper that refreshes the Forgejo token.
 
-A Bun port of the Python `ce` script from the `code.izy.sh/library/runner` image. Same commands, flags, environment variables, messages, exit codes and on-disk files, so a workflow only has to swap `ce` for `bunx`. Any job with Bun and an engine CLI can use it; it no longer needs the runner image.
+Started as a port of the Python `ce` script from the `code.izy.sh/library/runner` image, with the same commands, flags, environment variables and exit codes, so a workflow only has to swap `ce` for `npx` or `bunx`. It runs on Node (22.15 or later) and Bun. Any job with Node or Bun and an engine CLI can use it; it no longer needs the runner image.
 
 ## Usage
 
 ```sh
-bunx @izykitten/ce login
-bunx @izykitten/ce docker buildx build --push --cache type=gha,mode=max -t "$SERVER/$REPO:$REF,latest" .
+npx @izykitten/ce login
+npx @izykitten/ce docker buildx build --push --cache type=gha,mode=max -t "$SERVER/$REPO:$REF,latest" .
 ```
 
-When installed as a dependency, call it as `ce` (`bunx ce …`). Run `ce` with no arguments for the full help, including every environment variable `login` reads.
+`bunx @izykitten/ce …` works the same. The scripts run under `node`; `bun` runs them too when invoked as `bun node_modules/.bin/ce …` or through `bunx --bun`. When installed as a dependency, call it as `ce` (`npx ce …`). Run `ce` with no arguments for the full help, including every environment variable `login` reads.
 
 In a Forgejo workflow:
 
@@ -33,11 +33,23 @@ With `AUD` set (and `enable-openid-connect: true` on the job), `ce login` logs i
 
 The package installs `docker-credential-ce-forgejo` next to `ce`. `ce` puts that directory on `PATH` for the engines it starts, so `ce docker …` finds the helper. A plain `docker` command in a later step does not get that `PATH`, so run pushes to an OIDC registry through `ce`.
 
-## Differences from the Python version
+## Compatibility
 
-- Replacing the process with the engine (`execvp`) and the state-file lock (`flock`) go through `bun:ffi` to libc, since Bun has no API for either. Tested on glibc (Debian) and musl (Alpine). It takes the same kernel lock as the Python version, so both can share a Docker config.
-- The `Usage:` line shows the absolute path of the script, because Bun reports it that way.
-- Error text that comes from the system, network or JSON parser is Bun's wording, not Python's (for example `ENOENT: no such file or directory` rather than `[Errno 2] No such file or directory`). Messages written by `ce` itself are unchanged.
+These stay the same from release to release, and [test/contract.test.ts](test/contract.test.ts) checks them by running the built package under Node and Bun:
+
+- commands, flags and the environment variables `login` reads;
+- the arguments the engine receives after tag and cache rewriting, and its exit code, signals and PID (`ce` replaces itself with the engine);
+- `ce`'s own exit codes: 0 for help, 1 for a failure, 2 for bad arguments;
+- the order and arguments of `login`'s engine calls, with the password on stdin;
+- the credential-helper protocol, and the Docker config and `ce-forgejo-credentials.json` files `ce` writes.
+
+The wording of messages is not part of that and may change.
+
+Compared with the Python version:
+
+- The state file is locked with `ce-forgejo-credentials.json.pidlock`, holding the holder's PID and hostname, rather than `flock`, which Node does not have. A lock whose holder died is broken right away if the PID is gone on the same host, otherwise after two minutes. It does not exclude a Python `ce` using the same Docker config at the same moment.
+- Replacing the process with the engine uses `process.execve`. Node aborts rather than report an `execve` failure, so `ce` first checks that the engine is an executable file on `PATH`.
+- Messages are worded differently in places, and the `Usage:` line shows the absolute path of the script.
 - `docker-credential-ce-forgejo` runs the helper code directly instead of `exec ce credential-helper`, so `ce` does not have to be on `PATH`.
 - JSON files keep the same structure and sorted keys. Numbers are written as JavaScript writes them (`4102444800` rather than `4102444800.0`), and non-ASCII characters are not `\u`-escaped.
 
@@ -45,6 +57,7 @@ The package installs `docker-credential-ce-forgejo` next to `ce`. `ce` puts that
 
 ```sh
 bun install
-bun test          # the ported test_ce.py suite plus process tests for exec and flock
+bun test          # builds dist/, then unit tests plus the contract and process tests under Node and Bun
 bun check
+bun run build     # dist/ce.js, which the bin scripts load; npm pack runs it
 ```

package/bin/ce

@@ -1,6 +1,6 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 import path from "node:path";
-import { entry } from "../src/ce.ts";
+import { entry } from "../dist/ce.js";
 
 // The wrapper is only meaningful when invoked as `ce`; reject any other basename.
 const self = path.basename(process.argv[1] ?? "");

package/bin/docker-credential-ce-forgejo

@@ -1,5 +1,5 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 // Docker runs `docker-credential-<suffix>` for `"credHelpers": {"<host>": "ce-forgejo"}`.
-import { entry } from "../src/ce.ts";
+import { entry } from "../dist/ce.js";
 
 await entry(["credential-helper", ...process.argv.slice(2)]);