niral 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,109 @@
+# Niral CLI
+
+Zero-dependency launcher for the Niral full-stack framework. Requires Node.js 22+.
+
+## Use
+
+```sh
+npx niral create myapp
+cd myapp
+npx niral dev
+```
+
+Or install one global launcher:
+
+```sh
+npm install -g niral
+niral create myapp --template blog
+niral dev myapp
+```
+
+Both `niral` and `create-niral` packages provide the same two executable names.
+Install only one globally to avoid bin conflicts. Templates: `minimal` (default),
+`blog`, `dashboard`. Create refuses to overwrite a nonempty project directory.
+
+The first project command downloads the framework from the official
+[repository](https://github.com/Zyora-Dev/niral) into `~/.niral/framework`.
+Set `NIRAL_HOME` to choose another install directory. Normal commands reuse the
+cached framework without checking the network. Keep projects outside that directory.
+
+## Commands
+
+```sh
+npx niral --help
+npx niral --version
+npx niral check myapp
+npx niral test myapp
+npx niral build myapp
+npx niral start myapp
+npx niral add api myapp
+```
+
+All framework commands and arguments are forwarded, with the framework's exit
+status preserved. See the [complete CLI reference](https://niral.site/docs/cli).
+`--version` reports this launcher and, when installed, the framework version.
+The generated direct `niral` shim reports the framework version only.
+
+## Update
+
+Launcher 0.1.4 supports explicit framework updates and persisted revision pins:
+
+```sh
+npx niral@latest update
+```
+
+This explicitly updates `NIRAL_HOME/framework`, even when the cached framework
+has no `update` command. The default is the repository's `main` branch. Updating
+also refreshes an existing generated shell shim so its updater remains independent
+of older pinned framework code. Updating the npm launcher alone does not refresh
+the framework; update a globally installed launcher separately with
+`npm install -g niral@latest`.
+
+Set `APPROVED_FRAMEWORK_SHA` to a reviewed full 40-character lowercase commit SHA:
+
+```sh
+NIRAL_REF="$APPROVED_FRAMEWORK_SHA" npx niral@latest update
+niral update
+NIRAL_REF=main npx niral@latest update
+```
+
+The selection is saved in `NIRAL_HOME/.framework-ref`; plain updates retain it.
+Existing `v`-prefixed version tags are also accepted, but tags can move: use a
+full commit SHA for reproducibility. `NIRAL_REF=main` explicitly removes the pin.
+Fresh installations accept the same variable; switching a cached install requires
+an explicit update. npm versions and framework revisions are independent.
+
+Git installs must be clean, on `main` or a managed detached pin, and use the
+official HTTPS origin. `main` updates
+are fast-forward only; a Git failure never replaces the checkout with an archive.
+Pin changes and non-Git replacements are staged and syntax-checked first; the complete previous
+directory is retained at the printed `framework-backup-*/framework` path. Local
+files in that backup are not merged into the new framework. No backups are pruned.
+
+Stop active development/build commands before updating. Concurrent installers are
+refused. If interrupted, inspect other installer processes before manually removing
+a stale `NIRAL_HOME/.framework-install-lock` directory. Symlinked installs and
+updates invoked from unmanaged source checkouts are refused; maintain those with
+Git. An update does not migrate apps, publish packages or deploy/restart servers.
+
+## Developer Intelligence
+
+```sh
+npx niral di setup
+npx niral di status
+npx niral di ask "Explain this project" --root ./myapp --read-only
+npx niral di chat --root ./myapp
+npx niral di new myblog "Customize the home page" --template blog
+```
+
+`npx niral di setup` offers OpenAI, Claude (Anthropic), Azure OpenAI or Custom.
+Named providers set protocol/auth automatically; Custom keeps manual choices.
+Enter your exact model/deployment and credential variable name. Azure also asks
+for its resource URL or `/openai/v1` base. Bedrock is not yet supported.
+Use `npx niral di setup --help` for noninteractive flags.
+Credentials stay in a named environment variable, not config or project files.
+File reads/edits require a terminal and per-tool approval; writes retain backups
+and reject stale hashes. `ask <prompt> --no-tools` permits prompt-only automation.
+No unrestricted shell, automatic tests, transcript persistence or Niral Cloud
+requirement. See the [DI commands and safeguards](https://niral.site/docs/cli).
+Existing cached frameworks need `npx niral@latest update` to acquire DI commands.

package/bin/create-niral.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// npx create-niral my-app — the beginner's one command.
-import { ensureFramework, installLauncher, runNiral } from "../index.js";
+// npx create-niral my-app [--template blog|dashboard] — the beginner's one command.
+import { ensureFramework, installLauncher, runNiral, runLauncher } from "../index.js";
 
 const usage = "usage: npx create-niral <app-name|.> [--template minimal|blog|dashboard]";
 
@@ -9,8 +9,10 @@ async function main(argv = process.argv.slice(2)) {
     console.log(usage);
     return 0;
   }
+  if (argv.length === 1 && ["--version", "-v"].includes(argv[0])) return runLauncher(["--version"]);
   const name = argv[0];
   if (!name || (name.startsWith("-") && name !== ".")) throw new Error(usage);
+  if (argv.length !== 1 && !(argv.length === 3 && argv[1] === "--template" && ["minimal", "blog", "dashboard"].includes(argv[2]))) throw new Error(usage);
 
   await ensureFramework();
   const code = runNiral(["create", name, ...argv.slice(1)]);
@@ -19,6 +21,7 @@ async function main(argv = process.argv.slice(2)) {
   const { profile, added } = installLauncher();
   console.log("");
   if (added) console.log(`✓ \`niral\` command installed — PATH updated in ${profile} (open a new terminal)`);
+  if (!profile) console.log("Use npx niral <command>, or add NIRAL_HOME/bin to your PATH.");
   const cd = name === "." ? "" : `  cd ${name}\n`;
   console.log(`Next:\n${cd}  niral dev          # or: npx niral dev\n`);
   return 0;

package/bin/niral.js

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 // niral <command> — forwards to the framework at ~/.niral/framework.
 // Available globally after `npm i -g create-niral`, or per-call via `npx niral dev`.
-import { ensureFramework, runNiral } from "../index.js";
+import { runLauncher } from "../index.js";
 
 async function main() {
-	await ensureFramework();
-	return runNiral(process.argv.slice(2));
+	return runLauncher(process.argv.slice(2));
 }
 
 main().then((code) => {

package/index.js

@@ -6,29 +6,45 @@
  * forwards commands to it. The framework itself never touches npm.
  */
 
-import { existsSync, mkdirSync, rmSync, writeFileSync, chmodSync, appendFileSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, renameSync, lstatSync, realpathSync, rmSync, writeFileSync, chmodSync, appendFileSync, readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { get } from "node:https";
 
-export const NIRAL_HOME = process.env.NIRAL_HOME || join(homedir(), ".niral");
+export const NIRAL_HOME = resolve(process.env.NIRAL_HOME || join(homedir(), ".niral"));
 const FRAMEWORK = join(NIRAL_HOME, "framework");
-const TARBALL = "https://codeload.github.com/Zyora-Dev/niral/tar.gz/refs/heads/main";
 const REPO = "https://github.com/Zyora-Dev/niral.git";
 
 function download(url, dest) {
   return new Promise((resolve, reject) => {
-    get(url, (res) => {
-      if (res.statusCode !== 200) return reject(new Error(`download failed: HTTP ${res.statusCode}`));
+    const request = get(url, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`download failed: HTTP ${res.statusCode}`));
+      }
       const chunks = [];
-      res.on("data", (c) => chunks.push(c));
+      let bytes = 0;
+      res.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > 64 * 1024 * 1024) {
+          request.destroy(new Error("framework download exceeds 64 MiB"));
+          return;
+        }
+        chunks.push(chunk);
+      });
       res.on("end", () => {
-        writeFileSync(dest, Buffer.concat(chunks));
-        resolve();
+        try {
+          writeFileSync(dest, Buffer.concat(chunks));
+          resolve();
+        } catch (error) {
+          reject(error);
+        }
       });
       res.on("error", reject);
     }).on("error", reject);
+    const deadline = setTimeout(() => request.destroy(new Error("framework download timed out")), 60000);
+    request.on("close", () => clearTimeout(deadline));
   });
 }
 
@@ -42,51 +58,174 @@ function commandError(label, result) {
   return new Error(`${label} failed: ${detail}`);
 }
 
-async function installFromTarball() {
-  const tgz = join(NIRAL_HOME, "niral.tgz");
-  await download(TARBALL, tgz);
-  rmSync(FRAMEWORK, { recursive: true, force: true });
-  mkdirSync(FRAMEWORK, { recursive: true });
-  const extracted = spawnSync("tar", ["-xzf", tgz, "-C", FRAMEWORK, "--strip-components=1"], { encoding: "utf8" });
+async function installFromTarball(stage, ref) {
+  const tgz = join(stage, "niral.tgz");
+  await download(`https://codeload.github.com/Zyora-Dev/niral/tar.gz/${ref === "main" ? "refs/heads/main" : encodeURIComponent(ref)}`, tgz);
+  const target = join(stage, "framework");
+  mkdirSync(target);
+  const extracted = spawnSync("tar", ["-xzf", tgz, "-C", target, "--strip-components=1"], { encoding: "utf8", timeout: 120000 });
   rmSync(tgz, { force: true });
   if (extracted.error || extracted.status !== 0) throw commandError("framework extraction", extracted);
 }
 
 /** Download the framework to ~/.niral/framework (git if available, tarball otherwise). */
 export async function ensureFramework({ update = false } = {}) {
-  if (existsSync(join(FRAMEWORK, "bin", "niral.js")) && !update) return FRAMEWORK;
-  console.log("niral · downloading the framework (one time, ~1 MB — it has zero dependencies)…");
+  if (Number(process.versions.node.split(".")[0]) < 22) throw new Error("Niral requires Node.js 22 or newer");
+  const pinFile = join(NIRAL_HOME, ".framework-ref");
+  const previousRef = existsSync(pinFile) ? readFileSync(pinFile, "utf8").trim() : "main";
+  const ref = process.env.NIRAL_REF ?? previousRef;
+  if (!/^(?:main|[a-f0-9]{40}|v\d+\.\d+\.\d+(?:[-.][A-Za-z0-9.-]+)?)$/.test(ref)) throw new Error("NIRAL_REF must be main, a full lowercase commit SHA, or a v-prefixed version tag");
+  if (existsSync(join(FRAMEWORK, "bin", "niral.js")) && !update) {
+    if (ref !== previousRef) throw new Error("framework pin differs from the installed version; run niral update with NIRAL_REF set");
+    return FRAMEWORK;
+  }
   mkdirSync(NIRAL_HOME, { recursive: true });
-  let installed = false;
-  if (hasGit()) {
-    const gitResult = existsSync(join(FRAMEWORK, ".git"))
-      ? spawnSync("git", ["pull", "--ff-only", "-q"], { cwd: FRAMEWORK, encoding: "utf8" })
-      : (() => {
-          rmSync(FRAMEWORK, { recursive: true, force: true });
-          return spawnSync("git", ["clone", "-q", "--depth", "1", REPO, FRAMEWORK], { encoding: "utf8" });
-        })();
-    if (!gitResult.error && gitResult.status === 0) {
-      installed = true;
-    } else {
-      const reason = gitResult.error?.message || gitResult.stderr?.trim() || `exit ${gitResult.status ?? "unknown"}`;
-      console.warn(`niral · Git download unavailable (${reason}); trying the release tarball…`);
+  const lock = join(NIRAL_HOME, ".framework-install-lock");
+  try {
+    mkdirSync(lock);
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Error(`framework installation is locked: ${lock}. Check for another installer before removing a stale lock.`);
+    throw error;
+  }
+  let stage;
+  try {
+    if (existsSync(join(FRAMEWORK, "bin", "niral.js")) && !update) return FRAMEWORK;
+    const entry = lstatSync(FRAMEWORK, { throwIfNoEntry: false });
+    if (entry && (!entry.isDirectory() || entry.isSymbolicLink())) throw new Error("framework path must be a real directory; installation left unchanged");
+    console.log(update ? "niral: updating the installed framework..." : "niral: downloading the framework...");
+    if (existsSync(join(FRAMEWORK, ".git"))) {
+      if (!hasGit()) throw new Error("Git is required to update this checkout; installation left unchanged");
+      const git = (args) => {
+        const result = spawnSync("git", args, { cwd: FRAMEWORK, encoding: "utf8", timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+        if (result.error || result.status !== 0) throw commandError("Git update (no archive fallback)", result);
+        return result.stdout.trim();
+      };
+      if (git(["status", "--porcelain", "--untracked-files=all"])) throw new Error("framework checkout has local changes; preserve them before updating");
+      const branch = git(["branch", "--show-current"]);
+      if (branch !== "main" && !(previousRef !== "main" && branch === "")) throw new Error("framework checkout is not on main or a managed pin; update it manually with Git");
+      if (![REPO, REPO.replace(/\.git$/, "")].includes(git(["remote", "get-url", "origin"]))) throw new Error("framework origin differs from the official repository; update it manually with Git");
+      if (ref === "main" && previousRef === "main") {
+        const previous = git(["rev-parse", "HEAD"]);
+        git(["pull", "--ff-only", "origin", "main"]);
+        console.log(`niral: framework ${git(["rev-parse", "--short", "HEAD"])} (previous ${previous})`);
+        return FRAMEWORK;
+      }
+    }
+    stage = mkdtempSync(join(NIRAL_HOME, ".framework-stage-"));
+    const target = join(stage, "framework");
+    let installed = false;
+    if (hasGit()) {
+      const args = ref === "main" ? ["clone", "-q", "--depth", "1", "--branch", "main", REPO, target] : ["clone", "-q", "--no-checkout", REPO, target];
+      const cloned = spawnSync("git", args, {
+        encoding: "utf8", timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+      });
+      installed = !cloned.error && cloned.status === 0;
+      if (installed && ref !== "main") {
+        const checkedOut = spawnSync("git", ["checkout", "--detach", ref], { cwd: target, encoding: "utf8", timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+        if (checkedOut.error || checkedOut.status !== 0) throw commandError("pinned framework checkout", checkedOut);
+        if (/^[a-f0-9]{40}$/.test(ref)) {
+          const revision = spawnSync("git", ["rev-parse", "HEAD"], { cwd: target, encoding: "utf8", timeout: 10000 });
+          if (revision.status !== 0 || revision.stdout.trim() !== ref) throw new Error("pinned framework revision did not match the requested commit");
+        }
+      }
+      if (!installed) {
+        rmSync(target, { recursive: true, force: true });
+        console.warn("niral: Git download unavailable; trying the framework archive...");
+      }
     }
+    if (!installed) await installFromTarball(stage, ref);
+    const manifest = JSON.parse(readFileSync(join(target, "package.json"), "utf8"));
+    if (manifest.name !== "niral" || !existsSync(join(target, "src", "index.js"))) throw new Error("download is not a Niral framework");
+    const checked = spawnSync(process.execPath, ["--check", join(target, "bin", "niral.js")], { encoding: "utf8", timeout: 10000 });
+    if (checked.error || checked.status !== 0) throw commandError("downloaded CLI validation", checked);
+    const stagedPin = join(stage, "ref");
+    if (ref !== "main") writeFileSync(stagedPin, ref + "\n");
+    let backup;
+    if (entry) {
+      backup = join(mkdtempSync(join(NIRAL_HOME, "framework-backup-")), "framework");
+      renameSync(FRAMEWORK, backup);
+    }
+    try {
+      renameSync(target, FRAMEWORK);
+      if (ref === "main") rmSync(pinFile, { force: true });
+      else renameSync(stagedPin, pinFile);
+    } catch (error) {
+      if (existsSync(FRAMEWORK)) renameSync(FRAMEWORK, target);
+      if (backup) renameSync(backup, FRAMEWORK);
+      throw error;
+    }
+    if (backup) console.log(`niral: previous framework preserved at ${backup}`);
+    console.log(`niral: framework ${manifest.version} ready (${ref})`);
+    return FRAMEWORK;
+  } finally {
+    if (stage) rmSync(stage, { recursive: true, force: true });
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+export async function updateFramework({ sourceRoot } = {}) {
+  if (sourceRoot && (!existsSync(FRAMEWORK) || realpathSync(sourceRoot) !== realpathSync(FRAMEWORK))) {
+    throw new Error("niral update only updates the managed NIRAL_HOME/framework installation. Update source checkouts with Git; deploy servers separately.");
   }
-  if (!installed) await installFromTarball();
-  if (!existsSync(join(FRAMEWORK, "bin", "niral.js"))) throw new Error("framework download failed — try again or clone github.com/Zyora-Dev/niral manually");
-  return FRAMEWORK;
+  await ensureFramework({ update: true });
+}
+
+export async function runLauncher(args) {
+  if (args[0] === "update") {
+    if (args.length === 2 && ["--help", "-h"].includes(args[1])) {
+      console.log("usage: niral update\nUpdates NIRAL_HOME/framework using its saved NIRAL_REF (default main); does not update npm packages or deploy apps.");
+      return 0;
+    }
+    if (args.length !== 1) throw new Error("usage: niral update");
+    await updateFramework();
+    if (existsSync(join(NIRAL_HOME, "bin", process.platform === "win32" ? "niral.cmd" : "niral"))) installLauncher();
+    return 0;
+  }
+  if (!args.length || ["help", "--help", "-h"].includes(args[0])) {
+    if (existsSync(join(FRAMEWORK, "bin", "niral.js"))) return runNiral(args);
+    console.log("niral <command> [options]\nCommands: create, dev, build, start, check, test, add, doctor, di, update.\nThe first framework command downloads the framework.\nniral di --help: Developer Intelligence setup, status, ask, chat, new.\nniral update: explicitly refresh the installed framework.\nRun niral --help after installation for the full framework command list.");
+    return 0;
+  }
+  if (["--version", "-v", "version"].includes(args[0])) {
+    const manifest = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+    console.log(`${manifest.name} launcher ${manifest.version}`);
+    if (existsSync(join(FRAMEWORK, "package.json"))) {
+      const framework = JSON.parse(readFileSync(join(FRAMEWORK, "package.json"), "utf8"));
+      console.log(`niral framework ${framework.version}`);
+    }
+    return 0;
+  }
+  await ensureFramework();
+  return runNiral(args);
 }
 
 /** Put a `niral` launcher on the PATH so every later command is just `niral dev`. */
 export function installLauncher() {
   const binDir = join(NIRAL_HOME, "bin");
   mkdirSync(binDir, { recursive: true });
-  const frameworkCli = join(FRAMEWORK, "bin", "niral.js");
+  const launcherDir = join(NIRAL_HOME, "launcher");
+  mkdirSync(launcherDir, { recursive: true });
+  writeFileSync(join(launcherDir, "index.mjs"), readFileSync(new URL(import.meta.url)));
+  const frameworkCli = join(launcherDir, "run.mjs");
+  writeFileSync(frameworkCli, `import { ensureFramework, runLauncher, runNiral } from "./index.mjs";
+try {
+  const args = process.argv.slice(2);
+  if (args[0] === "update") process.exitCode = await runLauncher(args);
+  else {
+    await ensureFramework();
+    process.exitCode = runNiral(args);
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}
+`);
   const shim = join(binDir, process.platform === "win32" ? "niral.cmd" : "niral");
   if (process.platform === "win32") {
-    writeFileSync(shim, `@echo off\r\n"${process.execPath}" "${frameworkCli}" %*\r\n`);
+    writeFileSync(shim, `@echo off\r\nset "NIRAL_HOME=${NIRAL_HOME.replaceAll("%", "%%")}"\r\n"${process.execPath.replaceAll("%", "%%")}" "${frameworkCli.replaceAll("%", "%%")}" %*\r\n`);
   } else {
-    writeFileSync(shim, `#!/usr/bin/env sh\nexec "${process.execPath}" "${frameworkCli}" "$@"\n`);
+    const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+    writeFileSync(shim, `#!/usr/bin/env sh\nexport NIRAL_HOME=${quote(NIRAL_HOME)}\nexec ${quote(process.execPath)} ${quote(frameworkCli)} "$@"\n`);
     chmodSync(shim, 0o755);
   }
 
@@ -95,9 +234,11 @@ export function installLauncher() {
     : (process.env.SHELL ?? "").endsWith("/bash") ? join(homedir(), ".bashrc")
     : null;
   if (profile) {
-    const line = `export PATH="$HOME/.niral/bin:$PATH"`;
+    const line = NIRAL_HOME === join(homedir(), ".niral")
+      ? `export PATH="$HOME/.niral/bin:$PATH"`
+      : `export PATH='${binDir.replaceAll("'", "'\\''")}':"$PATH"`;
     const current = existsSync(profile) ? readFileSync(profile, "utf8") : "";
-    if (!current.includes(".niral/bin")) {
+    if (!current.split(/\r?\n/).includes(line)) {
       appendFileSync(profile, `\n# niral\n${line}\n`);
       return { shim, profile, added: true };
     }

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "niral",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Niral — the zero-dependency full-stack framework by ZyoraLabs. This package is a tiny launcher; the framework itself lives at github.com/Zyora-Dev/niral and has zero dependencies.",
   "bin": {
     "niral": "bin/niral.js",
     "create-niral": "bin/create-niral.js"
   },
   "type": "module",
+  "files": ["bin/", "index.js", "README.md"],
   "engines": { "node": ">=22" },
   "keywords": ["niral", "framework", "fullstack", "zero-dependencies", "ssr", "zyoralabs"],
-  "homepage": "https://niral.zyora.club",
+  "homepage": "https://niral.site",
   "repository": { "type": "git", "url": "git+https://github.com/Zyora-Dev/niral.git" },
   "license": "MIT",
   "dependencies": {}