@orkestrel/scaffold 0.0.108 → 0.0.109

package/dist/agents/skills/orkestrel-publish/scripts/window.js

@@ -1,63 +1,227 @@
-// Work the npm authentication window. Run from the checkout root:
-//   node .agents/skills/orkestrel-publish/scripts/window.ts --whoami [--wait SECONDS]
-//   node .agents/skills/orkestrel-publish/scripts/window.ts --login [--wait SECONDS]
-//   node .agents/skills/orkestrel-publish/scripts/window.ts --publish DIR... --otp CODE [--json]
-//   node .agents/skills/orkestrel-publish/scripts/window.ts --confirm NAME@VERSION... [--wait SECONDS]
-// --whoami reads `npm whoami` once, or polls it every 5 seconds until it answers or the wait ends.
-// --login prints the command the operator runs in a real terminal (npm offers its approval only to a
-// TTY, so no child of this script can hold it), then polls `npm whoami` until it answers or the wait
-// ends. --publish refuses linked worktrees and submodules found at a package or its ancestors,
-// and names a linked worktree's primary clone.
-// It then re-reads `npm whoami` immediately before the first upload and refuses when it
-// answers nothing, then runs `npm publish --ignore-scripts --browser=false --otp=CODE` in each
-// directory back to back under captured pipes (npm's non-TTY guard turns a refused code into
-// EOTP with no prompt, so the path needs no TTY), journals each upload to tmp/units/publish-<name>.log, reads the `+ name@version`
-// acceptance line, stops at the first refusal and names the package to resume from, then confirms
-// each accepted version against the registry. --confirm re-reads the registry for each name@version every 5
-// seconds until it serves the version or the wait (default 120 seconds) ends. Exit 0 when the mode
-// succeeded, 3 when it did not, 64 on usage.
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { parseJsonRecord, readList, readMissingFlags, readOption, readString, runNpm, } from "../../orkestrel-dispatch/scripts/helpers.js";
-const POLL_MS = 5_000;
-const ACCEPTED = /^\+ (\S+)@(\S+)\s*$/mu;
-function waitFor(ms) {
+/** Holds the milliseconds between two polls of the registry. */
+export const POLL_MS = 5_000;
+/** Matches the acceptance line `npm publish` prints and captures the name and the version. */
+export const ACCEPTED = /^\+ (\S+)@(\S+)\s*$/mu;
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS = [
+    '--whoami',
+    '--login',
+    '--publish',
+    '--confirm',
+    '--wait',
+    '--otp',
+    '--json',
+];
+/** Holds the usage line the script prints when no mode or two modes were given. */
+export const USAGE = 'usage: window.ts --whoami [--wait SECONDS] | --login [--wait SECONDS] | --publish DIR... --otp CODE [--json] | --confirm NAME@VERSION... [--wait SECONDS]';
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
+ * with `--` is a missing value, and the `--flag=value` form is not read.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--otp`.
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
+ * another flag.
+ */
+export function readOption(argv, name) {
+    const index = argv.indexOf(name);
+    const value = index === -1 ? undefined : argv[index + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
+/**
+ * Names the value flags a caller gave with no value.
+ *
+ * @param argv - The arguments after the script path.
+ * @param names - The flags that take a value.
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
+ */
+export function readMissingFlags(argv, names) {
+    return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
+}
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * Reads the arguments before a bare `--`, which opens a command a script passes on. A `--flag=value`
+ * argument is unknown, because the script reads no such form.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(argv, flags) {
+    const end = argv.indexOf('--');
+    return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
+}
+/**
+ * Reads the values that follow a flag up to the next flag.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--publish`.
+ * @returns The values between the flag and the next `--` argument, empty when the flag is absent.
+ */
+export function readList(argv, name) {
+    const index = argv.indexOf(name);
+    if (index === -1)
+        return [];
+    const rest = argv.slice(index + 1);
+    const end = rest.findIndex((argument) => argument.startsWith('--'));
+    return end === -1 ? rest : rest.slice(0, end);
+}
+/**
+ * Parses a whole text as one JSON object.
+ *
+ * @param text - A JSON document, formatted or not, such as a manifest.
+ * @returns The parsed object, or undefined when the text is not a JSON object.
+ */
+export function parseJsonRecord(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return Object.fromEntries(Object.entries(parsed));
+        }
+    }
+    catch { }
+    return undefined;
+}
+/**
+ * Reads a string member of a record.
+ *
+ * @param record - The record, or undefined.
+ * @param key - The member name.
+ * @returns The string, or undefined when the member is absent or not a string.
+ */
+export function readString(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Resolves the npm command for this host.
+ *
+ * @remarks
+ * The `npm-cli.js` entry beside the running Node binary spawns without a shell on every host; the
+ * `npm` shim on Windows is a `.cmd` file that needs one, so that path is the fallback alone.
+ *
+ * @returns The file to spawn, the arguments that precede npm's own, and whether a shell is needed.
+ */
+export function resolveNpm() {
+    const cli = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    if (existsSync(cli))
+        return { file: process.execPath, prefix: [cli], shell: false };
+    return { file: 'npm', prefix: [], shell: process.platform === 'win32' };
+}
+/**
+ * Runs npm with the given arguments and returns the finished child.
+ *
+ * @param args - The npm arguments, such as `['whoami']`.
+ * @param cwd - The working directory. Default: the current directory.
+ * @returns The spawn result with `utf8` stdout and stderr.
+ */
+export function runNpm(args, cwd) {
+    const npm = resolveNpm();
+    return spawnSync(npm.file, [...npm.prefix, ...args], {
+        encoding: 'utf8',
+        windowsHide: true,
+        shell: npm.shell,
+        maxBuffer: 64 * 1024 * 1024,
+        ...(cwd === undefined ? {} : { cwd }),
+    });
+}
+/**
+ * Waits for a number of milliseconds.
+ *
+ * @param ms - The delay.
+ * @returns A promise that settles after the delay.
+ */
+export function waitFor(ms) {
     return new Promise((settle) => {
         setTimeout(settle, ms);
     });
 }
-function readWhoami() {
+/**
+ * Reads the account `npm whoami` names once.
+ *
+ * @returns The user name, or undefined when npm exited nonzero or printed nothing.
+ */
+export function readWhoami() {
     const result = runNpm(['whoami']);
     const user = result.stdout.trim();
     return result.status === 0 && user !== '' ? user : undefined;
 }
-async function pollWhoami(waitSeconds, started = Date.now()) {
+/**
+ * Polls `npm whoami` until it answers or the wait ends.
+ *
+ * @param waitSeconds - How long to keep polling; 0 reads once.
+ * @param started - The millisecond the polling began. Default: now.
+ * @returns The user name, or undefined when none answered within the wait.
+ */
+export async function pollWhoami(waitSeconds, started = Date.now()) {
     const user = readWhoami();
     if (user !== undefined || Date.now() - started >= waitSeconds * 1000)
         return user;
     await waitFor(POLL_MS);
     return pollWhoami(waitSeconds, started);
 }
-function readServed(name, version) {
+/**
+ * Checks whether the registry serves one version of a package.
+ *
+ * @param name - The package name.
+ * @param version - The version.
+ * @returns True if `npm view` reads exactly that version; false otherwise.
+ */
+export function readServed(name, version) {
     const result = runNpm(['view', `${name}@${version}`, 'version', '--json']);
     return result.status === 0 && result.stdout.replace(/["\s]/gu, '') === version;
 }
-async function confirmServed(name, version, waitSeconds, started = Date.now()) {
+/**
+ * Polls the registry until it serves one version or the wait ends.
+ *
+ * @param name - The package name.
+ * @param version - The version.
+ * @param waitSeconds - How long to keep polling; 0 reads once.
+ * @param started - The millisecond the polling began. Default: now.
+ * @returns True if the registry served the version within the wait; false otherwise.
+ */
+export async function confirmServed(name, version, waitSeconds, started = Date.now()) {
     const served = readServed(name, version);
     if (served || Date.now() - started >= waitSeconds * 1000)
         return served;
     await waitFor(POLL_MS);
     return confirmServed(name, version, waitSeconds, started);
 }
-function findGitRoot(directory) {
+/**
+ * Finds the nearest directory at or above one that holds a `.git` entry.
+ *
+ * @param directory - The directory to start from.
+ * @returns The nearest directory with a `.git` entry, or the filesystem root when none has one.
+ */
+export function findGitRoot(directory) {
     return existsSync(join(directory, '.git')) || dirname(directory) === directory
         ? directory
         : findGitRoot(dirname(directory));
 }
-function readErrorCode(text) {
+/**
+ * Reads the error code npm printed.
+ *
+ * @param text - npm's standard error.
+ * @returns The first `E` code in the text, such as `EOTP` or `E401`, or undefined when none appears.
+ */
+export function readErrorCode(text) {
     return text.match(/\b(E[A-Z0-9]{3,}|EOTP|E401|E403|E404)\b/u)?.[1];
 }
-function readManifestName(directory) {
+/**
+ * Reads the name and version a directory's package manifest declares.
+ *
+ * @param directory - The directory that holds `package.json`.
+ * @returns The name and version, each undefined when the manifest is absent, unreadable, or lacks it.
+ */
+export function readManifestName(directory) {
     const path = join(directory, 'package.json');
     if (!existsSync(path))
         return { name: undefined, version: undefined };
@@ -69,7 +233,15 @@ function readManifestName(directory) {
         return { name: undefined, version: undefined };
     }
 }
-function publishPackage(directory, otp) {
+/**
+ * Publishes one package directory and journals the upload.
+ *
+ * @param directory - The package directory.
+ * @param otp - The account's one-time code.
+ * @returns The upload: accepted when npm exited 0 and printed the acceptance line, else refused with
+ * the error code npm named.
+ */
+export function publishPackage(directory, otp) {
     const manifest = readManifestName(directory);
     const journal = `tmp/units/publish-${(manifest.name ?? directory).replace(/[^A-Za-z0-9.-]+/gu, '-')}.log`;
     // The refusal code must survive an inherited silent npm log level.
@@ -97,7 +269,16 @@ function publishPackage(directory, otp) {
     }
     return upload;
 }
-async function publishAll(directories, otp, waitSeconds) {
+/**
+ * Publishes a batch back to back and confirms each accepted version.
+ *
+ * @param directories - The package directories, in publish order.
+ * @param otp - The account's one-time code.
+ * @param waitSeconds - How long to wait for the registry to serve each accepted version.
+ * @returns One upload per directory published, ending at the first refusal; a directory after it is
+ * not published.
+ */
+export async function publishAll(directories, otp, waitSeconds) {
     mkdirSync('tmp/units', { recursive: true });
     // A step after the first refusal returns the state unchanged, so nothing publishes past it.
     const { uploads } = directories.reduce((state, directory) => {
@@ -119,7 +300,18 @@ async function publishAll(directories, otp, waitSeconds) {
     }
     return confirmed;
 }
-async function main(argv) {
+/**
+ * Runs the mode the arguments name.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 when the mode succeeded, 3 when it did not, 64 on usage.
+ */
+export async function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`window: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`);
+        return 64;
+    }
     const missing = readMissingFlags(argv, ['--wait', '--otp']);
     if (missing.length > 0) {
         console.error(`window: ${missing.join(', ')} given with no value`);
@@ -199,20 +391,22 @@ async function main(argv) {
             console.error('usage: window.ts --confirm NAME@VERSION... [--wait SECONDS]');
             return 64;
         }
-        const readings = [];
+        const results = [];
         for (const target of targets) {
             const at = target.lastIndexOf('@');
-            readings.push({
+            results.push({
                 target,
                 served: await confirmServed(target.slice(0, at), target.slice(at + 1), wait),
             });
         }
-        console.log(JSON.stringify({ mode: 'confirm', readings }));
-        return readings.every((reading) => reading.served) ? 0 : 3;
+        console.log(JSON.stringify({ mode: 'confirm', results }));
+        return results.every((result) => result.served) ? 0 : 3;
     }
-    console.error('usage: window.ts --whoami [--wait SECONDS] | --login [--wait SECONDS] | --publish DIR... --otp CODE [--json] | --confirm NAME@VERSION... [--wait SECONDS]');
+    console.error(USAGE);
     return 64;
 }
-main(process.argv.slice(2)).then((code) => {
-    process.exitCode = code;
-});
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}