rastack 0.0.35 → 0.0.36

package/src/rastack-init.ts

@@ -1,34 +1,60 @@
 #!/usr/bin/env node
 
 /**
- * `rastack init` — template the base GitHub Actions + deploy config into a repo.
+ * `rastack init` — scaffold a repo's deploy config + GitHub Actions AND stand the
+ * serverless backend up.
  *
  *   rastack init [--app <slug>] [--owner <o>] [--repo <r>] [--branch <b>]
- *                [--region <r>] [--force] [--no-workflows] [--yes]
+ *                [--region <r>] [--prefix <p>] [--namespace <n>]
+ *                [--force] [--no-workflows] [--no-deploy] [--print] [--yes]
  *
- * Scaffolds a new project (or reconfigures an existing one) so it is ready to
- * deploy: `.rastack/deploy.json` plus `.github/workflows/{ci,deploy-backend}.yml`,
- * both of which run `rastack ci`. GitHub coordinates default from the repo's
- * `origin` remote; missing fields are prompted for on a TTY. Existing files are
- * left untouched unless `--force`.
+ * This is the one command that takes you from nothing to deployed. It:
+ *   1. writes `.rastack/deploy.json` + `.github/workflows/{ci,deploy-backend}.yml`
+ *      (GitHub coordinates default from the `origin` remote; missing fields are
+ *      prompted for on a TTY);
+ *   2. resolves the tier-0 bootstrap stack's artifacts bucket — and CREATES the
+ *      bootstrap stack if it does not exist yet;
+ *   3. uploads the Lambda placeholder bundle to that bucket;
+ *   4. deploys the per-app backend (app.yaml) with the resolved ArtifactsBucket;
+ *   5. reads the stack Outputs back into the config and prints the two GitHub repo
+ *      Variables CI needs.
+ *
+ * Thereafter the recurring code deploy is CI's job — `rastack ci deploy`, which
+ * `rastack deploy` also runs. `--no-deploy` scaffolds only; `--print` shows the
+ * exact single-line `aws cloudformation deploy` commands without running them.
  */
 
 import * as fs from "fs";
 import * as path from "path";
 import {
+  APP_STACK_OUTPUTS,
+  BOOTSTRAP_ARTIFACTS_OUTPUT,
+  BOOTSTRAP_TEMPLATES_OUTPUT,
   DeployConfig,
+  DeployOutputs,
   PartialDeployConfig,
+  bootstrapStackArgs,
+  bootstrapStackCommand,
+  bootstrapStackName,
+  deployStackArgs,
+  deployStackCommand,
   mergeConfig,
   normalizeConfig,
   parseGitHubRemote,
+  repoVariables,
   validateConfig,
 } from "./deploy/config";
 import { scaffoldFiles } from "./deploy/workflows";
 import {
   ask,
+  awsAvailable,
+  awsRun,
   canPrompt,
   gitRemoteUrl,
   loadConfig,
+  saveConfig,
+  stackOutput,
+  uploadPlaceholder,
   withPrompt,
 } from "./deploy/io";
 
@@ -36,6 +62,8 @@ interface Flags {
   patch: PartialDeployConfig;
   force: boolean;
   noWorkflows: boolean;
+  noDeploy: boolean;
+  print: boolean;
   nonInteractive: boolean;
 }
 
@@ -43,6 +71,8 @@ function parseFlags(argv: string[]): Flags {
   const patch: PartialDeployConfig = { github: {} };
   let force = false;
   let noWorkflows = false;
+  let noDeploy = false;
+  let print = false;
   let nonInteractive = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -66,12 +96,22 @@ function parseFlags(argv: string[]): Flags {
       case "--prefix":
         patch.namePrefix = next();
         break;
+      case "--namespace":
+        patch.namespace = next();
+        break;
       case "--force":
         force = true;
         break;
       case "--no-workflows":
         noWorkflows = true;
         break;
+      case "--no-deploy":
+        noDeploy = true;
+        break;
+      case "--print":
+      case "--dry-run":
+        print = true;
+        break;
       case "--yes":
       case "-y":
       case "--non-interactive":
@@ -84,7 +124,7 @@ function parseFlags(argv: string[]): Flags {
         }
     }
   }
-  return { patch, force, noWorkflows, nonInteractive };
+  return { patch, force, noWorkflows, noDeploy, print, nonInteractive };
 }
 
 /** Seed a config: existing file → flags → git remote → defaults. */
@@ -128,31 +168,220 @@ async function promptMissing(cfg: DeployConfig): Promise<DeployConfig> {
   });
 }
 
+/** Yes/no confirmation with a default of "no" — gates the cloud-mutating steps. */
+async function confirm(question: string): Promise<boolean> {
+  return withPrompt(async (rl) => {
+    const answer = await ask(rl, question, "no");
+    return /^y(es)?$/i.test(answer.trim());
+  });
+}
+
+/** Pad `Key  Value` rows into an aligned block. */
+function table(rows: { key: string; value: string }[]): string {
+  const width = Math.max(0, ...rows.map((r) => r.key.length));
+  return rows.map((r) => `    ${r.key.padEnd(width)}  ${r.value}`).join("\n");
+}
+
+/**
+ * Read the app.yaml stack Outputs into a `DeployOutputs`, skipping any that are
+ * not resolvable yet (best-effort — a freshly created stack has them all).
+ */
+function readAppOutputs(cfg: DeployConfig): DeployOutputs {
+  const outputs: DeployOutputs = {};
+  for (const { key, field } of APP_STACK_OUTPUTS) {
+    const value = stackOutput(cfg.stackName, key, cfg.region);
+    if (value) outputs[field] = value;
+  }
+  return outputs;
+}
+
+/**
+ * Print the exact commands `init` would run, without touching the cloud
+ * (`--print`). The artifacts bucket is read from the bootstrap stack when the
+ * AWS CLI is available, else shown as a placeholder.
+ */
+function printPlan(cfg: DeployConfig): void {
+  const bucket = awsAvailable()
+    ? stackOutput(
+        bootstrapStackName(cfg),
+        BOOTSTRAP_ARTIFACTS_OUTPUT,
+        cfg.region,
+      )
+    : null;
+  const withBucket = mergeConfig(cfg, {
+    artifactsBucket: bucket ?? "<ArtifactsBucketName from bootstrap stack>",
+  });
+  console.log(`\n  Deployment plan (${cfg.stackName} @ ${cfg.region})\n`);
+  console.log(
+    `  ── 1. Bootstrap stack (${bootstrapStackName(cfg)}) — run only if it does not exist ──`,
+  );
+  console.log("\n  " + bootstrapStackCommand(cfg) + "\n");
+  console.log("  ── 2. Per-app backend (app.yaml) ──");
+  console.log("\n  " + deployStackCommand(withBucket) + "\n");
+  console.log(
+    "  ── 3. Wire these GitHub repo Variables from the stack Outputs ──",
+  );
+  console.log(
+    table(
+      repoVariables(cfg).map((v) => ({
+        key: v.name,
+        value: v.value || `<${v.from}>`,
+      })),
+    ) + "\n",
+  );
+}
+
+/**
+ * Stand the infrastructure up: ensure the bootstrap stack + artifacts bucket,
+ * upload the Lambda placeholder, deploy app.yaml, and read the Outputs back into
+ * the config. Returns the config enriched with the resolved buckets + outputs.
+ */
+async function standUp(cfg: DeployConfig): Promise<DeployConfig> {
+  if (!awsAvailable()) {
+    console.error(
+      "  ✗ the AWS CLI is not on PATH. Install it and configure credentials,\n" +
+        "    or re-run with --print to see the commands, or --no-deploy to skip.",
+    );
+    process.exit(1);
+  }
+
+  // 1. Resolve the artifacts bucket; bootstrap the tier-0 stack if it is absent.
+  let artifactsBucket = stackOutput(
+    bootstrapStackName(cfg),
+    BOOTSTRAP_ARTIFACTS_OUTPUT,
+    cfg.region,
+  );
+  let templatesBucket = stackOutput(
+    bootstrapStackName(cfg),
+    BOOTSTRAP_TEMPLATES_OUTPUT,
+    cfg.region,
+  );
+  if (!artifactsBucket) {
+    console.log(
+      `\n▸ Bootstrap stack ${bootstrapStackName(cfg)} not found — creating it (once per account+region).`,
+    );
+    deployBootstrap(cfg);
+    artifactsBucket = stackOutput(
+      bootstrapStackName(cfg),
+      BOOTSTRAP_ARTIFACTS_OUTPUT,
+      cfg.region,
+    );
+    templatesBucket = stackOutput(
+      bootstrapStackName(cfg),
+      BOOTSTRAP_TEMPLATES_OUTPUT,
+      cfg.region,
+    );
+    if (!artifactsBucket) {
+      console.error(
+        "  ✗ bootstrap stack created but its ArtifactsBucket output could not be read.",
+      );
+      process.exit(1);
+    }
+  }
+  console.log(`  ✓ artifacts bucket: ${artifactsBucket}`);
+
+  // 2. Upload the placeholder the function is created from.
+  console.log("\n▸ Uploading the Lambda placeholder bundle");
+  if (!uploadPlaceholder(artifactsBucket, cfg.region)) {
+    console.error(
+      "  ✗ deploy/cloudformation/placeholder/bootstrap not found — cannot create the function.",
+    );
+    process.exit(1);
+  }
+
+  // 3. Deploy the per-app backend with the resolved bucket wired in.
+  cfg = mergeConfig(cfg, {
+    artifactsBucket,
+    templatesBucket: templatesBucket ?? undefined,
+  });
+  console.log(`\n▸ Deploying ${cfg.stackName}`);
+  try {
+    awsRun(deployStackArgs(cfg));
+  } catch (err) {
+    console.error(
+      `\n  ✗ aws cloudformation deploy failed for ${cfg.stackName}.\n    ${(err as Error).message}`,
+    );
+    process.exit(1);
+  }
+
+  // 4. Read the Outputs back into the config so CI has them without a live lookup.
+  const outputs = readAppOutputs(cfg);
+  cfg = mergeConfig(cfg, { outputs });
+  saveConfig(cfg);
+  return cfg;
+}
+
+/** Deploy the bootstrap stack, retrying once against an existing OIDC provider. */
+function deployBootstrap(cfg: DeployConfig): void {
+  try {
+    awsRun(bootstrapStackArgs(cfg));
+  } catch {
+    // The most common cause is an account that already has a GitHub OIDC
+    // provider (only one is allowed per URL). Retry telling the template to
+    // reuse it instead of creating a second.
+    console.log(
+      "  • retrying bootstrap, reusing the account's existing GitHub OIDC provider",
+    );
+    try {
+      awsRun(bootstrapStackArgs(cfg, true));
+    } catch (err) {
+      console.error(
+        `\n  ✗ bootstrap stack deploy failed.\n    ${(err as Error).message}`,
+      );
+      process.exit(1);
+    }
+  }
+}
+
+function printSummary(cfg: DeployConfig): void {
+  console.log(
+    `\n  ✓ ${cfg.app} is deployed (${cfg.stackName} @ ${cfg.region})`,
+  );
+  if (cfg.outputs?.apiUrl) console.log(`    API:  ${cfg.outputs.apiUrl}`);
+  console.log(
+    "\n  Wire these GitHub repo Variables so CI can ship code (Settings → Variables):",
+  );
+  console.log(
+    table(
+      repoVariables(cfg).map((v) => ({
+        key: v.name,
+        value: v.value || `<${v.from}>`,
+      })),
+    ),
+  );
+  console.log(
+    `\n  Then every push to ${cfg.github.branch} ships code via \`rastack ci deploy\`` +
+      ` (also runnable locally as \`rastack deploy\`).\n`,
+  );
+}
+
 async function main(argv: string[]): Promise<void> {
   const flags = parseFlags(argv);
   let cfg = seedConfig(flags);
 
   if (canPrompt(flags.nonInteractive)) {
     console.log(
-      "\n  rastack init — scaffold the deploy config + GitHub Actions\n",
+      "\n  rastack init — scaffold the deploy config + stand the backend up\n",
     );
     cfg = await promptMissing(cfg);
   }
 
   const errors = validateConfig(cfg);
-  // In non-interactive mode a still-incomplete config is fatal; interactively we
-  // still write what we have so the user can finish it in the file, but warn.
+  // Any deploy needs a complete config; a still-incomplete one is fatal unless we
+  // are only scaffolding files.
   if (errors.length) {
-    const label = flags.nonInteractive ? "✗" : "⚠";
+    const fatal = !flags.noDeploy || flags.nonInteractive;
+    const label = fatal ? "✗" : "⚠";
     for (const e of errors) console.error(`  ${label} ${e}`);
-    if (flags.nonInteractive) {
+    if (fatal) {
       console.error(
-        `\n  ${errors.length} problem(s). Pass the missing values as flags.`,
+        `\n  ${errors.length} problem(s). Pass the missing values as flags, or --no-deploy to scaffold only.`,
       );
       process.exit(1);
     }
   }
 
+  // 1. Scaffold the config + workflows.
   const files = scaffoldFiles(cfg, { noWorkflows: flags.noWorkflows });
   const written: string[] = [];
   const skipped: string[] = [];
@@ -166,17 +395,38 @@ async function main(argv: string[]): Promise<void> {
     fs.writeFileSync(abs, f.content);
     written.push(f.path);
   }
-
   console.log("");
   for (const w of written) console.log(`  ✓ wrote ${w}`);
   for (const s of skipped)
     console.log(`  • skipped ${s} (exists — pass --force to overwrite)`);
-  console.log(
-    `\n  Next:\n` +
-      `    1. rastack deploy   — review the config and print the stack launch command\n` +
-      `    2. create the CloudFormation stack (once), then wire the repo Variables it prints\n` +
-      `    3. push to ${cfg.github.branch} — CI runs \`rastack ci deploy\`\n`,
-  );
+
+  // 2. Deploy (unless opted out).
+  if (flags.print) {
+    printPlan(cfg);
+    return;
+  }
+  if (flags.noDeploy) {
+    console.log(
+      `\n  Config scaffolded. Run \`rastack init\` again (without --no-deploy) to deploy,\n` +
+        `  or \`rastack init --print\` to see the exact commands.\n`,
+    );
+    return;
+  }
+
+  if (canPrompt(flags.nonInteractive)) {
+    const ok = await confirm(
+      `Deploy ${cfg.stackName} to AWS ${cfg.region} now? (creates the bootstrap stack if needed) [y/N]`,
+    );
+    if (!ok) {
+      console.log(
+        "\n  Skipped the deploy. Re-run to deploy, or `rastack init --print` for the commands.\n",
+      );
+      return;
+    }
+  }
+
+  cfg = await standUp(cfg);
+  printSummary(cfg);
 }
 
 if (require.main === module) {

package/src/rastack-update.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+/**
+ * `rastack update` — update the CLI in place.
+ *
+ *   rastack update [<version>] [--version <v>] [--check] [--dry-run]
+ *
+ *   (no args)        update to the latest published version
+ *   <version>        pin a target, e.g. `rastack update 0.0.40`
+ *   --check          report current vs. latest, install nothing
+ *   --dry-run        print the npm command that would run, don't run it
+ *
+ * `rastack` is a global npm package installed into a self-contained per-user
+ * prefix (`~/.rastack`, via the hosted installer). Updating re-runs
+ * `npm install -g rastack@<target>` against that SAME prefix — derived from where
+ * the running CLI lives — so it never scatters a second copy into npm's default
+ * global location. Pure decisions live in `update.ts`; this is the IO wrapper.
+ */
+
+import { execFileSync } from "child_process";
+import { readFileSync } from "fs";
+import * as path from "path";
+import {
+  globalPrefixFromPackageDir,
+  npmInstallArgs,
+  parseUpdateFlags,
+  updateAvailable,
+} from "./update";
+
+/** The installed rastack package directory (…/rastack), one up from dist/. */
+const PKG_DIR = path.join(__dirname, "..");
+const PKG_JSON = path.join(PKG_DIR, "package.json");
+
+/** Read the version from a package.json on disk, or "unknown" if unreadable. */
+function readVersion(file: string): string {
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/** Capture `npm <args>` stdout, or null when npm is absent / the call fails. */
+function npmCapture(args: string[]): string | null {
+  try {
+    return execFileSync("npm", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+      .toString()
+      .trim();
+  } catch {
+    return null;
+  }
+}
+
+function main(argv: string[]): void {
+  const flags = parseUpdateFlags(argv);
+  const current = readVersion(PKG_JSON);
+  const prefix = globalPrefixFromPackageDir(PKG_DIR);
+
+  // The npm prefix must land the update where this CLI actually lives.
+  const env = { ...process.env };
+  if (prefix) env.npm_config_prefix = prefix;
+
+  if (flags.check) {
+    const latest = npmCapture(["view", "rastack@latest", "version"]);
+    if (!latest) {
+      console.error(
+        "  ✗ could not reach the npm registry to check for updates.",
+      );
+      process.exit(1);
+    }
+    console.log(`  rastack ${current} (installed) — latest is ${latest}`);
+    if (updateAvailable(current, latest)) {
+      console.log(`  ▸ run \`rastack update\` to upgrade to ${latest}.`);
+    } else {
+      console.log("  ✓ you are on the latest version.");
+    }
+    return;
+  }
+
+  const args = npmInstallArgs(flags.version);
+  if (flags.dryRun) {
+    const pfx = prefix ? `npm_config_prefix=${prefix} ` : "";
+    console.log(`\n  ${pfx}npm ${args.join(" ")}\n`);
+    return;
+  }
+
+  if (!prefix) {
+    // Running from a source checkout (not a global install) — nothing to self-update.
+    console.error(
+      "  ✗ rastack is not running from a global install, so `update` does not apply.\n" +
+        "    Reinstall with the hosted installer, or `npm install -g rastack` to manage it.",
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `\n▸ Updating rastack (${current} → ${flags.version}) in ${prefix}\n`,
+  );
+  try {
+    // Re-runs the developer's own npm to update this global package — no
+    // untrusted input, and execFileSync (no shell) avoids any injection.
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+    execFileSync("npm", args, { stdio: "inherit", env });
+  } catch (err) {
+    console.error(
+      `\n  ✗ npm failed to update rastack. Re-run for detail:\n    npm install -g ${npmInstallArgs(flags.version)[2]}\n    ${(err as Error).message}`,
+    );
+    process.exit(1);
+  }
+
+  // Re-read the (now replaced) package.json to report where we landed.
+  const updated = readVersion(PKG_JSON);
+  if (updated === current) {
+    console.log(`\n  ✓ rastack is up to date (${updated}).\n`);
+  } else {
+    console.log(`\n  ✓ rastack updated ${current} → ${updated}.\n`);
+  }
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/rastack.ts

@@ -16,9 +16,10 @@
  *   rastack wasm                                Compile the API to WebAssembly (in-browser local dev)
  *   rastack scan   [files...] [--fail-on-pii]   Scan CSVs for PII and schema info
  *   rastack seed   [--env dev] [--source gs://] Load CSVs into Iceberg namespace
- *   rastack init   [--app slug] [--force]       Template the base GitHub Actions + deploy config
- *   rastack deploy [--print] [--run]            Configure the serverless deployment
+ *   rastack init   [--app slug] [--force]       Scaffold config + GitHub Actions AND stand the backend up
+ *   rastack deploy [--plan]                     Ship code to the Lambda (alias for `rastack ci deploy`)
  *   rastack ci     <check|build|deploy> [--plan] Run the CI pipeline (keeps Actions a one-liner)
+ *   rastack update [<version>] [--check]        Update the CLI in place (self-update)
  */
 
 import { execSync, spawnSync } from "child_process";
@@ -118,17 +119,23 @@ switch (command) {
     run("seed.js");
     break;
   case "init":
-    // Template the base GitHub Actions + deploy config into a repo.
+    // Scaffold config + GitHub Actions and stand the serverless backend up.
     run("rastack-init.js", rest);
     break;
   case "deploy":
-    // Configure the serverless deployment (writes .rastack/deploy.json).
-    run("rastack-deploy.js", rest);
+    // Ship code to the Lambda — an alias for the CI code deploy. Infrastructure
+    // is stood up once by `rastack init`; `deploy` only ever ships code.
+    run("rastack-ci.js", ["deploy", ...rest]);
     break;
   case "ci":
     // Run a CI pipeline phase (check | build | deploy).
     run("rastack-ci.js", rest);
     break;
+  case "update":
+  case "upgrade":
+    // Self-update the globally-installed CLI in place.
+    run("rastack-update.js", rest);
+    break;
   case "generate":
   case "gen":
     // Proxy to existing rastack codegen pipeline
@@ -147,9 +154,10 @@ switch (command) {
         `  rastack wasm                                Compile the API to WebAssembly (browser local dev)\n` +
         `  rastack scan   [files...] [--fail-on-pii]\n` +
         `  rastack seed   [--env dev|staging] [--source gs://bucket/ | ./myapp-dev/]\n` +
-        `  rastack init   [--app slug] [--owner o] [--repo r] [--force]  Template GitHub Actions + deploy config\n` +
-        `  rastack deploy [--app slug] [--print] [--run]                 Configure the serverless deployment\n` +
-        `  rastack ci     <check|build|deploy> [--plan]                  Run the CI pipeline (cleaner Actions)\n`,
+        `  rastack init   [--app slug] [--owner o] [--repo r] [--print] [--no-deploy]  Scaffold + stand the backend up\n` +
+        `  rastack deploy [--plan]                                       Ship code to the Lambda (alias for ci deploy)\n` +
+        `  rastack ci     <check|build|deploy> [--plan]                  Run the CI pipeline (cleaner Actions)\n` +
+        `  rastack update [<version>] [--check] [--dry-run]              Update the CLI in place (self-update)\n`,
     );
     process.exit(1);
 }

package/src/update.ts

@@ -0,0 +1,114 @@
+/**
+ * Pure core of `rastack update` — the CLI's self-updater.
+ *
+ * `rastack` is installed with `npm install -g rastack` into a self-contained
+ * per-user prefix (`~/.rastack`, wired by web/public/setup.{sh,ps1}), so updating
+ * is just re-running that global install against the SAME prefix the running CLI
+ * lives in — then reporting the version change. Everything decidable without IO
+ * lives here (flag parsing, the npm argv, deriving the prefix from the install
+ * path, semver comparison) so it is unit-tested without npm or the network;
+ * `rastack-update.ts` is the thin wrapper that shells out.
+ */
+
+export interface UpdateFlags {
+  /** `latest`, or a pinned semver like `0.0.40`. */
+  version: string;
+  /** Only report current vs. latest — do not install. */
+  check: boolean;
+  /** Print the npm command that would run, without running it. */
+  dryRun: boolean;
+}
+
+/**
+ * Parse `rastack update` args. Accepts `--check`, `--dry-run`/`--print`, and a
+ * version either as `--version <v>` or as a bare positional (`rastack update
+ * 0.0.40`). Unknown values default to `latest`.
+ */
+export function parseUpdateFlags(argv: string[]): UpdateFlags {
+  let version = "latest";
+  let check = false;
+  let dryRun = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--check":
+        check = true;
+        break;
+      case "--dry-run":
+      case "--print":
+        dryRun = true;
+        break;
+      case "--version":
+      case "--to":
+        version = argv[++i] ?? "latest";
+        break;
+      default:
+        // A bare, non-flag token is taken as the target version.
+        if (!a.startsWith("-")) version = a;
+    }
+  }
+  return { version, check, dryRun };
+}
+
+/** The npm package spec to install for a target version. */
+export function installSpec(version: string): string {
+  return !version || version === "latest" ? "rastack" : `rastack@${version}`;
+}
+
+/** The `npm <args>` (after the `npm` binary) that installs the target globally. */
+export function npmInstallArgs(version: string): string[] {
+  return [
+    "install",
+    "-g",
+    installSpec(version),
+    "--no-fund",
+    "--no-audit",
+    "--loglevel=error",
+  ];
+}
+
+/**
+ * Derive the npm global prefix from the installed rastack package directory, so
+ * the update lands in the SAME location the running CLI was installed to (not
+ * npm's default global prefix, which may differ from the per-user `~/.rastack`).
+ *
+ * Global installs put the package at `<prefix>/lib/node_modules/rastack` (POSIX)
+ * or `<prefix>/node_modules/rastack` (Windows). Returns null when rastack is not
+ * under a `node_modules` at all — e.g. running from a source checkout — where
+ * self-update does not apply.
+ */
+export function globalPrefixFromPackageDir(pkgDir: string): string | null {
+  const norm = pkgDir.replace(/\\/g, "/");
+  // Length-preserving normalization, so indices map back onto the original.
+  const posix = norm.lastIndexOf("/lib/node_modules/");
+  if (posix !== -1) return pkgDir.slice(0, posix);
+  const win = norm.lastIndexOf("/node_modules/");
+  if (win !== -1) return pkgDir.slice(0, win);
+  return null;
+}
+
+/**
+ * Compare two dotted versions numerically (major.minor.patch; any pre-release
+ * suffix is ignored). Returns -1 if a < b, 1 if a > b, 0 if equal — enough to
+ * tell `--check` whether an update is available.
+ */
+export function compareSemver(a: string, b: string): number {
+  const parts = (v: string) =>
+    v
+      .replace(/^v/, "")
+      .split("-")[0]
+      .split(".")
+      .map((n) => parseInt(n, 10) || 0);
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** True when `latest` is a strictly newer version than `current`. */
+export function updateAvailable(current: string, latest: string): boolean {
+  return compareSemver(current, latest) < 0;
+}