shellman 0.1.0 → 0.1.1-dev.0

package/README.md

@@ -4,13 +4,36 @@ Global installer package for Shellman.
 
 ## Install
 
+Stable channel:
+
 ```bash
 npm install -g shellman
 ```
 
-The installer downloads a prebuilt release package from GitHub Releases for:
+Dev channel:
+
+```bash
+npm install -g shellman@dev
+```
+
+## How It Works
+
+- `postinstall` reads `release.json` from GitHub Releases.
+- It picks the matching artifact for the current platform and verifies SHA-256.
+- Supported targets:
+  - darwin-arm64
+  - darwin-amd64
+  - linux-arm64
+  - linux-amd64
+
+At runtime, `shellman` checks remote `release.json` periodically and prints an upgrade hint when a newer channel version is available.
+
+## Environment Variables
 
-- darwin-arm64
-- darwin-amd64
-- linux-arm64
-- linux-amd64
+- `SHELLMAN_RELEASE_CHANNEL=stable|dev`
+- `SHELLMAN_GITHUB_REPO=owner/repo`
+- `SHELLMAN_RELEASE_MANIFEST_URL=https://.../release.json`
+- `SHELLMAN_SKIP_POSTINSTALL=1`
+- `SHELLMAN_FORCE_POSTINSTALL=1`
+- `SHELLMAN_NO_UPDATE_CHECK=1`
+- `SHELLMAN_UPDATE_CHECK_INTERVAL_SEC=43200`

package/bin/shellman.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, platform, arch } from "node:os";
 import path from "node:path";
 import process from "node:process";
@@ -17,28 +17,168 @@ function resolveTargetTriple() {
   return "";
 }
 
-function resolveInstalledBinary() {
+function getPackageMeta() {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  const version = String(pkg.version ?? "").trim();
+  return { version };
+}
+
+function getChannel(pkgVersion) {
+  const forced = String(process.env.SHELLMAN_RELEASE_CHANNEL ?? "").trim();
+  if (forced === "stable" || forced === "dev") {
+    return forced;
+  }
+  return pkgVersion.includes("-dev") ? "dev" : "stable";
+}
+
+function getRepo() {
+  const raw = (process.env.SHELLMAN_GITHUB_REPO || "thecybersailor/shellman").trim();
+  return raw || "thecybersailor/shellman";
+}
+
+function getManifestURL(channel) {
+  const custom = String(process.env.SHELLMAN_RELEASE_MANIFEST_URL ?? "").trim();
+  if (custom) {
+    return custom;
+  }
+  const repo = getRepo();
+  if (channel === "dev") {
+    return `https://github.com/${repo}/releases/download/dev-main/release.json`;
+  }
+  return `https://github.com/${repo}/releases/latest/download/release.json`;
+}
+
+function resolveInstalledBinary(channel, pkgVersion) {
   const triple = resolveTargetTriple();
   if (!triple) {
     console.error(`shellman: unsupported platform ${platform()}/${arch()} (only darwin/linux + arm64/x64 supported)`);
     process.exit(1);
   }
 
-  const pkgVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-  const installRoot = path.join(homedir(), ".shellman", "versions", `v${pkgVersion}`, triple, "bin");
-  const binPath = path.join(installRoot, "shellman");
+  const channelRoot = path.join(homedir(), ".shellman", "channels", channel, triple);
+  const channelBin = path.join(channelRoot, "bin", "shellman");
+  if (existsSync(channelBin)) {
+    return {
+      binPath: channelBin,
+      versionFile: path.join(channelRoot, "VERSION")
+    };
+  }
 
-  if (!existsSync(binPath)) {
-    console.error("shellman: prebuilt binary is not installed. Reinstall package:");
-    console.error("  npm install -g shellman");
-    process.exit(1);
+  const legacyRoot = path.join(homedir(), ".shellman", "versions", `v${pkgVersion}`, triple);
+  const legacyBin = path.join(legacyRoot, "bin", "shellman");
+  if (existsSync(legacyBin)) {
+    return {
+      binPath: legacyBin,
+      versionFile: path.join(legacyRoot, "VERSION")
+    };
+  }
+
+  console.error("shellman: prebuilt binary is not installed. Reinstall package:");
+  console.error(`  npm install -g ${channel === "dev" ? "shellman@dev" : "shellman"}`);
+  process.exit(1);
+}
+
+function readInstalledVersion(fallbackVersion, versionFile) {
+  if (!existsSync(versionFile)) {
+    return fallbackVersion;
+  }
+  const raw = String(readFileSync(versionFile, "utf8")).trim();
+  if (!raw) {
+    return fallbackVersion;
+  }
+  return raw.replace(/^v/, "");
+}
+
+function shouldSkipUpdateCheck() {
+  return String(process.env.SHELLMAN_NO_UPDATE_CHECK ?? "").trim() === "1";
+}
+
+function getUpdateCheckIntervalSec() {
+  const raw = String(process.env.SHELLMAN_UPDATE_CHECK_INTERVAL_SEC ?? "").trim();
+  const parsed = Number(raw);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return Math.floor(parsed);
+  }
+  return 43200;
+}
+
+function loadUpdateCache(cachePath) {
+  if (!existsSync(cachePath)) {
+    return { checkedAt: 0, lastNotifiedVersion: "" };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+    return {
+      checkedAt: Number(parsed.checkedAt ?? 0),
+      lastNotifiedVersion: String(parsed.lastNotifiedVersion ?? "")
+    };
+  } catch {
+    return { checkedAt: 0, lastNotifiedVersion: "" };
+  }
+}
+
+function saveUpdateCache(cachePath, payload) {
+  mkdirSync(path.dirname(cachePath), { recursive: true });
+  writeFileSync(cachePath, JSON.stringify(payload), "utf8");
+}
+
+async function checkForUpdateNotice({ channel, installedVersion }) {
+  if (shouldSkipUpdateCheck()) {
+    return;
+  }
+
+  const cachePath = path.join(homedir(), ".shellman", "cache", `update-${channel}.json`);
+  const nowSec = Math.floor(Date.now() / 1000);
+  const intervalSec = getUpdateCheckIntervalSec();
+  const cache = loadUpdateCache(cachePath);
+  if (nowSec - cache.checkedAt < intervalSec) {
+    return;
   }
 
-  return binPath;
+  try {
+    const manifestURL = getManifestURL(channel);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2500);
+    const res = await fetch(manifestURL, {
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+
+    if (!res.ok) {
+      saveUpdateCache(cachePath, { checkedAt: nowSec, lastNotifiedVersion: cache.lastNotifiedVersion });
+      return;
+    }
+
+    const manifest = await res.json();
+    const remoteVersion = String(manifest?.version ?? "").trim().replace(/^v/, "");
+    if (!remoteVersion) {
+      saveUpdateCache(cachePath, { checkedAt: nowSec, lastNotifiedVersion: cache.lastNotifiedVersion });
+      return;
+    }
+
+    if (remoteVersion !== installedVersion && cache.lastNotifiedVersion !== remoteVersion) {
+      const upgradeCmd = channel === "dev" ? "npm install -g shellman@dev" : "npm install -g shellman";
+      console.error(`shellman: update available (${channel}) current=${installedVersion} latest=${remoteVersion}`);
+      console.error(`shellman: run \`${upgradeCmd}\``);
+      saveUpdateCache(cachePath, { checkedAt: nowSec, lastNotifiedVersion: remoteVersion });
+      return;
+    }
+
+    saveUpdateCache(cachePath, { checkedAt: nowSec, lastNotifiedVersion: cache.lastNotifiedVersion });
+  } catch {
+    saveUpdateCache(cachePath, { checkedAt: nowSec, lastNotifiedVersion: cache.lastNotifiedVersion });
+  }
 }
 
-const bin = resolveInstalledBinary();
-const child = spawn(bin, process.argv.slice(2), {
+const { version: pkgVersion } = getPackageMeta();
+const channel = getChannel(pkgVersion);
+const resolved = resolveInstalledBinary(channel, pkgVersion);
+const installedVersion = readInstalledVersion(pkgVersion, resolved.versionFile);
+
+void checkForUpdateNotice({ channel, installedVersion });
+
+const child = spawn(resolved.binPath, process.argv.slice(2), {
   stdio: "inherit",
   env: process.env,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellman",
-  "version": "0.1.0",
+  "version": "0.1.1-dev.0",
   "description": "Shellman CLI installer package",
   "license": "AGPL-3.0",
   "type": "module",

package/scripts/postinstall.js

@@ -18,22 +18,39 @@ function resolveTargetTriple() {
   return "";
 }
 
-function getPackageVersion() {
+function getPackageMeta() {
   const packageJSON = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-  return packageJSON.version;
+  const version = String(packageJSON.version ?? "").trim();
+  return { version };
+}
+
+function getChannel(pkgVersion) {
+  const forced = String(process.env.SHELLMAN_RELEASE_CHANNEL ?? "").trim();
+  if (forced === "stable" || forced === "dev") {
+    return forced;
+  }
+  return pkgVersion.includes("-dev") ? "dev" : "stable";
 }
 
 function getRepo() {
-  const raw = (process.env.SHELLMAN_GITHUB_REPO || "cybersailor/shellman-project").trim();
-  return raw || "cybersailor/shellman-project";
+  const raw = (process.env.SHELLMAN_GITHUB_REPO || "thecybersailor/shellman").trim();
+  return raw || "thecybersailor/shellman";
 }
 
-function getDownloadBase(version) {
-  const customBase = (process.env.SHELLMAN_DOWNLOAD_BASE_URL || "").trim();
-  if (customBase) {
-    return customBase.replace(/\/+$/, "");
+function getManifestURL(channel) {
+  const custom = String(process.env.SHELLMAN_RELEASE_MANIFEST_URL ?? "").trim();
+  if (custom) {
+    return custom;
   }
-  return `https://github.com/${getRepo()}/releases/download/v${version}`;
+  const repo = getRepo();
+  if (channel === "dev") {
+    return `https://github.com/${repo}/releases/download/dev-main/release.json`;
+  }
+  return `https://github.com/${repo}/releases/latest/download/release.json`;
+}
+
+function getInstallRoot(channel, triple) {
+  return path.join(homedir(), ".shellman", "channels", channel, triple);
 }
 
 async function download(url, outFile) {
@@ -44,23 +61,45 @@ async function download(url, outFile) {
   await pipeline(Readable.fromWeb(res.body), createWriteStream(outFile));
 }
 
+async function fetchJSON(url) {
+  const res = await fetch(url, { headers: { Accept: "application/json" } });
+  if (!res.ok) {
+    throw new Error(`manifest request failed ${res.status} ${res.statusText}: ${url}`);
+  }
+  return res.json();
+}
+
 function sha256File(filePath) {
   const hash = createHash("sha256");
   hash.update(readFileSync(filePath));
   return hash.digest("hex");
 }
 
-function parseSHA256Sums(filePath) {
-  const lines = readFileSync(filePath, "utf8").split(/\r?\n/);
-  const out = new Map();
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    const m = trimmed.match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/);
-    if (!m) continue;
-    out.set(m[2].trim(), m[1].toLowerCase());
-  }
-  return out;
+function resolveReleaseAsset(manifest, triple) {
+  const version = String(manifest?.version ?? "").trim();
+  const baseURL = String(manifest?.base_url ?? "").replace(/\/+$/, "");
+  const artifacts = Array.isArray(manifest?.artifacts) ? manifest.artifacts : [];
+  const hit = artifacts.find((item) => String(item?.target ?? "") === triple);
+  if (!version) {
+    throw new Error("invalid release manifest: missing version");
+  }
+  if (!baseURL) {
+    throw new Error("invalid release manifest: missing base_url");
+  }
+  if (!hit) {
+    throw new Error(`release manifest missing target: ${triple}`);
+  }
+  const file = String(hit.file ?? "").trim();
+  const sha256 = String(hit.sha256 ?? "").trim().toLowerCase();
+  if (!file || !sha256) {
+    throw new Error(`release manifest target incomplete: ${triple}`);
+  }
+  return {
+    version,
+    file,
+    sha256,
+    url: `${baseURL}/${file}`
+  };
 }
 
 async function main() {
@@ -68,6 +107,12 @@ async function main() {
     console.log("shellman: skip postinstall by SHELLMAN_SKIP_POSTINSTALL=1");
     return;
   }
+  const forcePostinstall = String(process.env.SHELLMAN_FORCE_POSTINSTALL ?? "").trim() === "1";
+  const isGlobalInstall = String(process.env.npm_config_global ?? "").trim() === "true";
+  if (!forcePostinstall && !isGlobalInstall) {
+    console.log("shellman: skip postinstall for non-global install");
+    return;
+  }
 
   const triple = resolveTargetTriple();
   if (!triple) {
@@ -75,53 +120,43 @@ async function main() {
     process.exit(1);
   }
 
-  const version = getPackageVersion();
-  const assetName = `shellman-v${version}-${triple}.zip`;
-  const checksumsName = "SHA256SUMS";
-  const base = getDownloadBase(version);
-
-  const installRoot = path.join(homedir(), ".shellman", "versions", `v${version}`, triple);
+  const { version: pkgVersion } = getPackageMeta();
+  const channel = getChannel(pkgVersion);
+  const installRoot = getInstallRoot(channel, triple);
   const binPath = path.join(installRoot, "bin", "shellman");
+
   if (existsSync(binPath)) {
     console.log(`shellman: binary already installed at ${binPath}`);
     return;
   }
 
-  const tmpRoot = path.join(homedir(), ".shellman", "tmp", `v${version}-${triple}`);
+  const manifestURL = getManifestURL(channel);
+  console.log(`shellman: reading release manifest (${channel}) ${manifestURL}`);
+  const manifest = await fetchJSON(manifestURL);
+  const releaseAsset = resolveReleaseAsset(manifest, triple);
+
+  const tmpRoot = path.join(homedir(), ".shellman", "tmp", `${channel}-${triple}`);
   rmSync(tmpRoot, { recursive: true, force: true });
   mkdirSync(tmpRoot, { recursive: true });
 
-  const zipPath = path.join(tmpRoot, assetName);
-  const sumsPath = path.join(tmpRoot, checksumsName);
-  const zipURL = `${base}/${assetName}`;
-  const sumsURL = `${base}/${checksumsName}`;
+  const zipPath = path.join(tmpRoot, releaseAsset.file);
+  console.log(`shellman: downloading ${releaseAsset.url}`);
+  await download(releaseAsset.url, zipPath);
 
-  console.log(`shellman: downloading ${zipURL}`);
-  await download(zipURL, zipPath);
-  await download(sumsURL, sumsPath);
-
-  const parsed = parseSHA256Sums(sumsPath);
-  const expected = parsed.get(assetName);
-  if (!expected) {
-    throw new Error(`missing checksum entry for ${assetName}`);
-  }
   const actual = sha256File(zipPath);
-  if (actual !== expected) {
-    throw new Error(`checksum mismatch for ${assetName}`);
+  if (actual !== releaseAsset.sha256) {
+    throw new Error(`checksum mismatch for ${releaseAsset.file}`);
   }
 
   rmSync(installRoot, { recursive: true, force: true });
   mkdirSync(installRoot, { recursive: true });
-  await pipeline(
-    createReadStream(zipPath),
-    unzipper.Extract({ path: installRoot }),
-  );
+  await pipeline(createReadStream(zipPath), unzipper.Extract({ path: installRoot }));
 
   if (!existsSync(binPath)) {
     throw new Error(`installed package missing binary: ${binPath}`);
   }
 
-  console.log(`shellman: installed v${version} for ${triple}`);
+  console.log(`shellman: installed ${releaseAsset.version} (${channel}) for ${triple}`);
 }
 
 main().catch((error) => {