@jacebenson/jsn 4.3.12-dev.70 → 4.3.13-dev.71.1

package/README.md

@@ -13,6 +13,47 @@ jsn setup
 
 See the [setup guide](docs/docs-setup.md) to connect an instance safely.
 
+### Dev channel
+
+For the newest changes from `main`, including changes that may be unstable:
+
+```bash
+npm install -g @jacebenson/jsn@dev
+```
+
+Dev builds check the dev channel for updates during normal use, at most once
+per day. Run `jsn version --check` to check immediately. To install the newest
+dev build, run `npm install -g @jacebenson/jsn@dev` again. Updates are manual.
+Return to stable with `npm install -g @jacebenson/jsn@latest`.
+
+Pushes to `main` promote the commit to `dev` and publish a tested prerelease
+under npm's `dev` tag. Versions include the workflow run number and attempt
+(for example, `4.3.9-dev.123.1`); they do not move npm's stable `latest` tag.
+The npm trusted publisher for `publish-dev.yml` must authorize the repository's
+`dev` GitHub environment, alongside the production publishing configuration.
+
+### Supported versions
+
+Only the current release and the two preceding releases in each channel are
+supported (three stable releases and three dev builds). For example, with
+stable `4.3.11`, versions `4.3.11`, `4.3.10`, and `4.3.9` are supported.
+Update to the newest version in your channel before reporting an issue.
+
+After each successful npm publish, deployment deprecates older versions in that
+channel. Deprecated versions remain installable and appear in history, but npm
+prints an update warning on installation. Existing deprecation messages are
+preserved. No versions are unpublished.
+
+The deprecation step uses the repository's `NPM_TOKEN` secret with permission to
+modify `@jacebenson/jsn` and noninteractive authentication (including bypass 2FA
+where required). Publishing continues to use OIDC. A deprecation failure fails
+the workflow after publishing; it does not roll back the published package.
+To retry only deprecation after fixing authentication, use the matching release
+checkout and run `node scripts/deprecate-old-versions.mjs latest --apply` (or
+`dev --apply`) with npm authentication configured and `NODE_AUTH_TOKEN` set.
+Omit `--apply` to preview the affected versions without changing npm. The script
+requires the checkout's package version to match the channel's current npm tag.
+
 ## Try it
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.12-dev.70",
+  "version": "4.3.13-dev.71.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -36,7 +36,7 @@ import { platformCmd } from './commands/platform.js';
 import { codesearchCmd } from './commands/codesearch.js';
 import { versionCmd } from './commands/version.js';
 import { skillCmd, checkSkill } from './commands/skill.js';
-import { getVersion, checkLatest } from './commands/version.js';
+import { getVersion, checkLatest, getReleaseChannel, getInstallCommand } from './commands/version.js';
 import { docsCmd } from './commands/docs/docs.js';
 
 // Table and platform commands registered at root level for progressive disclosure
@@ -290,7 +290,7 @@ export function buildCLI() {
         }
       }
       if (!skipNpmCheck) {
-        const cacheFile = path.join(globalConfigDir(), '.last-npm-check');
+        const cacheFile = path.join(globalConfigDir(), `.last-npm-check-${getReleaseChannel()}`);
         let shouldCheck = true;
         try {
           const mtime = fs.statSync(cacheFile).mtimeMs;
@@ -303,9 +303,9 @@ export function buildCLI() {
 
         if (shouldCheck) {
           const version = getVersion();
-          checkLatest({ background: true }).then(latest => {
+          checkLatest({ background: true, version }).then(latest => {
             if (latest && version !== latest) {
-              process.stderr.write(`\n⚠ jsn ${latest} available (you have ${version}) — run "npm install -g @jacebenson/jsn" to update\n\n`);
+              process.stderr.write(`\n⚠ jsn ${latest} available (you have ${version}) — run "${getInstallCommand(version)}" to update\n\n`);
             }
           }).catch(() => {});
 

package/src/commands/version.js

@@ -6,7 +6,13 @@ import { declareCapabilities } from '../capabilities.js';
 declareCapabilities('version', { noInstance: true, skipDailyChecks: true });
 
 const NPM_PKG = '@jacebenson/jsn';
-const NPM_REGISTRY = `https://registry.npmjs.org/${NPM_PKG}/latest`;
+export function getReleaseChannel(version = getVersion()) {
+  return /^\d+\.\d+\.\d+-dev\./.test(version) ? 'dev' : 'latest';
+}
+
+export function getInstallCommand(version = getVersion()) {
+  return `npm install -g ${NPM_PKG}${getReleaseChannel(version) === 'dev' ? '@dev' : ''}`;
+}
 
 export function getVersion() {
   try {
@@ -26,16 +32,16 @@ export function cancelBackgroundChecks() {
   backgroundChecks.clear();
 }
 
-export async function checkLatest({ timeout = 1500, background = false } = {}) {
+export async function checkLatest({ timeout = 1500, background = false, version = getVersion() } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
   timer.unref();
   if (background) backgroundChecks.add(controller);
   try {
-    const res = await fetch(NPM_REGISTRY, { signal: controller.signal });
+    const res = await fetch(`https://registry.npmjs.org/${NPM_PKG}/${getReleaseChannel(version)}`, { signal: controller.signal });
     if (!res.ok) return null;
     const data = await res.json();
-    return data.version;
+    return typeof data.version === 'string' ? data.version : null;
   } catch {
     return null;
   } finally {
@@ -58,11 +64,11 @@ export function versionCmd(wrap) {
       const version = getVersion();
 
       if (argv.check) {
-        const latest = await checkLatest();
+        const latest = await checkLatest({ version });
         if (!latest) {
           app.ok({ version }, {
             summary: `jsn ${version} (could not reach npm registry to check for updates)`,
-            notice: `Run \`npm view ${NPM_PKG}\` directly to check manually`,
+            notice: `Run \`npm view ${NPM_PKG}@${getReleaseChannel(version)} version\` directly to check manually`,
           });
           return;
         }
@@ -82,11 +88,11 @@ export function versionCmd(wrap) {
             version,
             latest,
             upToDate: false,
-            installCmd: `npm install -g ${NPM_PKG}`,
+            installCmd: getInstallCommand(version),
           }, {
             summary: `jsn ${version} — newer version ${latest} available`,
             breadcrumbs: [
-              { action: 'update', cmd: `npm install -g ${NPM_PKG}`, description: `Update jsn from ${version} to ${latest}` },
+              { action: 'update', cmd: getInstallCommand(version), description: `Update jsn from ${version} to ${latest}` },
             ],
           });
         }