niral 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,90 @@
+# 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.3 supports explicit framework updates:
+
+```sh
+npx niral@latest update
+```
+
+This explicitly updates `NIRAL_HOME/framework` from the repository's `main`
+branch, even when the cached framework has no `update` command. After updating,
+the direct `niral update` command is available too. Updates follow `main`, not
+a version-pinned release. Updating the npm launcher alone does not refresh the
+framework; update a globally installed launcher separately with
+`npm install -g niral@latest`.
+
+Git installs must be clean, on `main`, and use the official HTTPS origin. Updates
+are fast-forward only; a Git failure never replaces the checkout with an archive.
+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 --help
+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
+```
+
+Configure your exact protocol, API base, model/deployment and auth with `di setup`.
+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,21 +1,35 @@
 #!/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 name = process.argv[2];
-if (!name || name.startsWith("-")) {
-  console.error("usage: npx create-niral <app-name>");
-  process.exit(1);
-}
+const usage = "usage: npx create-niral <app-name|.> [--template minimal|blog|dashboard]";
+
+async function main(argv = process.argv.slice(2)) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    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]);
-if (code !== 0) process.exit(code);
+  await ensureFramework();
+  const code = runNiral(["create", name, ...argv.slice(1)]);
+  if (code !== 0) return code;
+
+  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;
+}
 
-const { profile, added } = installLauncher();
-console.log("");
-if (added) console.log(`✓ \`niral\` command installed — PATH updated in ${profile} (open a new terminal)`);
-console.log(`Next:
-  cd ${name}
-  niral dev          # or: npx niral dev
-`);
+main().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  console.error(`create-niral: ${error?.message || error}`);
+  process.exitCode = 1;
+});

package/bin/niral.js

@@ -1,7 +1,15 @@
 #!/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";
 
-await ensureFramework();
-process.exit(runNiral(process.argv.slice(2)));
+async function main() {
+	return runLauncher(process.argv.slice(2));
+}
+
+main().then((code) => {
+	process.exitCode = code;
+}).catch((error) => {
+	console.error(`niral: ${error?.message || error}`);
+	process.exitCode = 1;
+});

package/index.js

@@ -6,81 +6,199 @@
  * forwards commands to it. The framework itself never touches npm.
  */
 
-import { existsSync, mkdirSync, rmSync, writeFileSync, chmodSync, appendFileSync, readFileSync } from "node:fs";
-import { spawnSync, execSync } from "node:child_process";
-import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, renameSync, lstatSync, realpathSync, rmSync, writeFileSync, chmodSync, appendFileSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+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));
   });
 }
 
 function hasGit() {
-  try {
-    execSync("git --version", { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
+  const result = spawnSync("git", ["--version"], { stdio: "ignore" });
+  return !result.error && result.status === 0;
+}
+
+function commandError(label, result) {
+  const detail = result.error?.message || result.stderr?.trim() || `exit ${result.status ?? "unknown"}`;
+  return new Error(`${label} failed: ${detail}`);
+}
+
+async function installFromTarball(stage) {
+  const tgz = join(stage, "niral.tgz");
+  await download(TARBALL, 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 (Number(process.versions.node.split(".")[0]) < 22) throw new Error("Niral requires Node.js 22 or newer");
   if (existsSync(join(FRAMEWORK, "bin", "niral.js")) && !update) return FRAMEWORK;
-  console.log("niral · downloading the framework (one time, ~1 MB — it has zero dependencies)…");
   mkdirSync(NIRAL_HOME, { recursive: true });
-  if (hasGit()) {
+  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"))) {
-      execSync("git pull -q", { cwd: FRAMEWORK, stdio: "ignore" });
-    } else {
-      rmSync(FRAMEWORK, { recursive: true, force: true });
-      execSync(`git clone -q --depth 1 ${REPO} "${FRAMEWORK}"`, { stdio: "ignore" });
+      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");
+      if (git(["branch", "--show-current"]) !== "main") throw new Error("framework checkout is not on main; 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");
+      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;
     }
-  } else {
-    const tgz = join(NIRAL_HOME, "niral.tgz");
-    await download(TARBALL, tgz);
-    rmSync(FRAMEWORK, { recursive: true, force: true });
-    mkdirSync(FRAMEWORK, { recursive: true });
-    execSync(`tar -xzf "${tgz}" -C "${FRAMEWORK}" --strip-components=1`, { stdio: "ignore" });
-    rmSync(tgz);
+    stage = mkdtempSync(join(NIRAL_HOME, ".framework-stage-"));
+    const target = join(stage, "framework");
+    let installed = false;
+    if (hasGit()) {
+      const cloned = spawnSync("git", ["clone", "-q", "--depth", "1", "--branch", "main", REPO, target], {
+        encoding: "utf8", timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+      });
+      installed = !cloned.error && cloned.status === 0;
+      if (!installed) {
+        rmSync(target, { recursive: true, force: true });
+        console.warn("niral: Git download unavailable; trying the framework archive...");
+      }
+    }
+    if (!installed) await installFromTarball(stage);
+    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);
+    let backup;
+    if (entry) {
+      backup = join(mkdtempSync(join(NIRAL_HOME, "framework-backup-")), "framework");
+      renameSync(FRAMEWORK, backup);
+    }
+    try {
+      renameSync(target, FRAMEWORK);
+    } catch (error) {
+      if (backup) renameSync(backup, FRAMEWORK);
+      throw error;
+    }
+    if (backup) console.log(`niral: previous framework preserved at ${backup}`);
+    console.log(`niral: framework ${manifest.version} ready`);
+    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 (!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 from main; does not update npm packages or deploy apps.");
+      return 0;
+    }
+    if (args.length !== 1) throw new Error("usage: niral update");
+    await updateFramework();
+    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 shim = join(binDir, "niral");
-  writeFileSync(shim, `#!/usr/bin/env bash\nexec node "${join(FRAMEWORK, "bin", "niral.js")}" "$@"\n`);
-  chmodSync(shim, 0o755);
+  const frameworkCli = join(FRAMEWORK, "bin", "niral.js");
+  const shim = join(binDir, process.platform === "win32" ? "niral.cmd" : "niral");
+  if (process.platform === "win32") {
+    writeFileSync(shim, `@echo off\r\nset "NIRAL_HOME=${NIRAL_HOME.replaceAll("%", "%%")}"\r\n"${process.execPath.replaceAll("%", "%%")}" "${frameworkCli.replaceAll("%", "%%")}" %*\r\n`);
+  } else {
+    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);
+  }
 
   const profile =
     (process.env.SHELL ?? "").endsWith("/zsh") ? join(homedir(), ".zshrc")
     : (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 };
     }
@@ -91,6 +209,9 @@ export function installLauncher() {
 
 /** Forward a command to the framework CLI. */
 export function runNiral(args) {
-  const r = spawnSync("node", [join(FRAMEWORK, "bin", "niral.js"), ...args], { stdio: "inherit" });
-  return r.status ?? 0;
+  const r = spawnSync(process.execPath, [join(FRAMEWORK, "bin", "niral.js"), ...args], { stdio: "inherit" });
+  if (r.error) throw new Error(`could not start the Niral CLI: ${r.error.message}`);
+  if (r.signal) throw new Error(`Niral CLI terminated by ${r.signal}`);
+  if (r.status === null) throw new Error("Niral CLI exited without a status");
+  return r.status;
 }

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "niral",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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": {}