rastack 0.0.34 → 0.0.36

package/dist/rastack-init.js

@@ -1,16 +1,27 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * `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.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -55,6 +66,8 @@ function parseFlags(argv) {
     const patch = { 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];
@@ -78,12 +91,22 @@ function parseFlags(argv) {
             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":
@@ -96,7 +119,7 @@ function parseFlags(argv) {
                 }
         }
     }
-    return { patch, force, noWorkflows, nonInteractive };
+    return { patch, force, noWorkflows, noDeploy, print, nonInteractive };
 }
 /** Seed a config: existing file → flags → git remote → defaults. */
 function seedConfig(flags) {
@@ -133,25 +156,156 @@ async function promptMissing(cfg) {
         });
     });
 }
+/** Yes/no confirmation with a default of "no" — gates the cloud-mutating steps. */
+async function confirm(question) {
+    return (0, io_1.withPrompt)(async (rl) => {
+        const answer = await (0, io_1.ask)(rl, question, "no");
+        return /^y(es)?$/i.test(answer.trim());
+    });
+}
+/** Pad `Key  Value` rows into an aligned block. */
+function table(rows) {
+    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) {
+    const outputs = {};
+    for (const { key, field } of config_1.APP_STACK_OUTPUTS) {
+        const value = (0, io_1.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) {
+    const bucket = (0, io_1.awsAvailable)()
+        ? (0, io_1.stackOutput)((0, config_1.bootstrapStackName)(cfg), config_1.BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region)
+        : null;
+    const withBucket = (0, config_1.mergeConfig)(cfg, {
+        artifactsBucket: bucket ?? "<ArtifactsBucketName from bootstrap stack>",
+    });
+    console.log(`\n  Deployment plan (${cfg.stackName} @ ${cfg.region})\n`);
+    console.log(`  ── 1. Bootstrap stack (${(0, config_1.bootstrapStackName)(cfg)}) — run only if it does not exist ──`);
+    console.log("\n  " + (0, config_1.bootstrapStackCommand)(cfg) + "\n");
+    console.log("  ── 2. Per-app backend (app.yaml) ──");
+    console.log("\n  " + (0, config_1.deployStackCommand)(withBucket) + "\n");
+    console.log("  ── 3. Wire these GitHub repo Variables from the stack Outputs ──");
+    console.log(table((0, config_1.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) {
+    if (!(0, io_1.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 = (0, io_1.stackOutput)((0, config_1.bootstrapStackName)(cfg), config_1.BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region);
+    let templatesBucket = (0, io_1.stackOutput)((0, config_1.bootstrapStackName)(cfg), config_1.BOOTSTRAP_TEMPLATES_OUTPUT, cfg.region);
+    if (!artifactsBucket) {
+        console.log(`\n▸ Bootstrap stack ${(0, config_1.bootstrapStackName)(cfg)} not found — creating it (once per account+region).`);
+        deployBootstrap(cfg);
+        artifactsBucket = (0, io_1.stackOutput)((0, config_1.bootstrapStackName)(cfg), config_1.BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region);
+        templatesBucket = (0, io_1.stackOutput)((0, config_1.bootstrapStackName)(cfg), config_1.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 (!(0, io_1.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 = (0, config_1.mergeConfig)(cfg, {
+        artifactsBucket,
+        templatesBucket: templatesBucket ?? undefined,
+    });
+    console.log(`\n▸ Deploying ${cfg.stackName}`);
+    try {
+        (0, io_1.awsRun)((0, config_1.deployStackArgs)(cfg));
+    }
+    catch (err) {
+        console.error(`\n  ✗ aws cloudformation deploy failed for ${cfg.stackName}.\n    ${err.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 = (0, config_1.mergeConfig)(cfg, { outputs });
+    (0, io_1.saveConfig)(cfg);
+    return cfg;
+}
+/** Deploy the bootstrap stack, retrying once against an existing OIDC provider. */
+function deployBootstrap(cfg) {
+    try {
+        (0, io_1.awsRun)((0, config_1.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 {
+            (0, io_1.awsRun)((0, config_1.bootstrapStackArgs)(cfg, true));
+        }
+        catch (err) {
+            console.error(`\n  ✗ bootstrap stack deploy failed.\n    ${err.message}`);
+            process.exit(1);
+        }
+    }
+}
+function printSummary(cfg) {
+    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((0, config_1.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) {
     const flags = parseFlags(argv);
     let cfg = seedConfig(flags);
     if ((0, io_1.canPrompt)(flags.nonInteractive)) {
-        console.log("\n  rastack init — scaffold the deploy config + GitHub Actions\n");
+        console.log("\n  rastack init — scaffold the deploy config + stand the backend up\n");
         cfg = await promptMissing(cfg);
     }
     const errors = (0, config_1.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) {
-            console.error(`\n  ${errors.length} problem(s). Pass the missing values as flags.`);
+        if (fatal) {
+            console.error(`\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 = (0, workflows_1.scaffoldFiles)(cfg, { noWorkflows: flags.noWorkflows });
     const written = [];
     const skipped = [];
@@ -170,10 +324,25 @@ async function main(argv) {
         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 ((0, io_1.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) {
     main(process.argv.slice(2)).catch((err) => {

package/dist/rastack-update.d.ts

@@ -0,0 +1,18 @@
+#!/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.
+ */
+export {};

package/dist/rastack-update.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const update_1 = require("./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) {
+    try {
+        return JSON.parse((0, fs_1.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) {
+    try {
+        return (0, child_process_1.execFileSync)("npm", args, {
+            stdio: ["ignore", "pipe", "pipe"],
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+function main(argv) {
+    const flags = (0, update_1.parseUpdateFlags)(argv);
+    const current = readVersion(PKG_JSON);
+    const prefix = (0, update_1.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 ((0, update_1.updateAvailable)(current, latest)) {
+            console.log(`  ▸ run \`rastack update\` to upgrade to ${latest}.`);
+        }
+        else {
+            console.log("  ✓ you are on the latest version.");
+        }
+        return;
+    }
+    const args = (0, update_1.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
+        (0, child_process_1.execFileSync)("npm", args, { stdio: "inherit", env });
+    }
+    catch (err) {
+        console.error(`\n  ✗ npm failed to update rastack. Re-run for detail:\n    npm install -g ${(0, update_1.npmInstallArgs)(flags.version)[2]}\n    ${err.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/dist/rastack.d.ts

@@ -15,8 +15,9 @@
  *   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)
  */
 export {};

package/dist/rastack.js

@@ -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)
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -113,17 +114,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
@@ -141,8 +148,9 @@ 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/dist/update.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 declare function parseUpdateFlags(argv: string[]): UpdateFlags;
+/** The npm package spec to install for a target version. */
+export declare function installSpec(version: string): string;
+/** The `npm <args>` (after the `npm` binary) that installs the target globally. */
+export declare function npmInstallArgs(version: string): string[];
+/**
+ * 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 declare function globalPrefixFromPackageDir(pkgDir: string): string | 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 declare function compareSemver(a: string, b: string): number;
+/** True when `latest` is a strictly newer version than `current`. */
+export declare function updateAvailable(current: string, latest: string): boolean;

package/dist/update.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUpdateFlags = parseUpdateFlags;
+exports.installSpec = installSpec;
+exports.npmInstallArgs = npmInstallArgs;
+exports.globalPrefixFromPackageDir = globalPrefixFromPackageDir;
+exports.compareSemver = compareSemver;
+exports.updateAvailable = updateAvailable;
+/**
+ * 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`.
+ */
+function parseUpdateFlags(argv) {
+    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. */
+function installSpec(version) {
+    return !version || version === "latest" ? "rastack" : `rastack@${version}`;
+}
+/** The `npm <args>` (after the `npm` binary) that installs the target globally. */
+function npmInstallArgs(version) {
+    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.
+ */
+function globalPrefixFromPackageDir(pkgDir) {
+    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.
+ */
+function compareSemver(a, b) {
+    const parts = (v) => 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`. */
+function updateAvailable(current, latest) {
+    return compareSemver(current, latest) < 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.34",
+  "version": "0.0.36",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",