hirmos 1.3.0 → 1.3.2

package/README.md

@@ -5,27 +5,30 @@ Product-facing HIRMOS CLI.
 Implemented command:
 
 ```bash
-hirmos init [project-path] [--integration <ids>] [--source <path>]
+hirmos init [project-path] [--integration <ids>] [--source <path>] [--version <version>] [--offline]
 ```
 
 The CLI makes an installed HIRMOS project discoverable to selected agent-native tools by generating thin bootstrap integration files from `_hirmos/integrations/agent-tools/`.
 
-It does not invoke agents, run HIRMOS workflows, install extensions, download remote packages, or generate slash-command packs.
+It does not invoke agents, run HIRMOS workflows, install extensions, or generate slash-command packs.
 
 ## Usage
 
-From a project that already contains `_hirmos/`:
+From a project root:
 
 ```bash
 hirmos init
 ```
 
+If `_hirmos/` is not present, the CLI downloads the latest HIRMOS framework release package and installs `_hirmos/` before generating integrations.
+
 This defaults to:
 
 ```text
 project-path = .
 integration = agents
-source = existing _hirmos/ in the project
+source = existing _hirmos/ in the project, otherwise latest GitHub release
+version = latest
 ```
 
 Generate specific integrations:
@@ -40,12 +43,41 @@ Initialize another project path:
 hirmos init /path/to/project --integration agents,claude
 ```
 
-Install `_hirmos/` from a local source folder or release zip when the target project does not already contain `_hirmos/`:
+Install a specific HIRMOS release:
+
+```bash
+hirmos init --version 1.3.1
+```
+
+Install `_hirmos/` from a local source folder or release zip instead of downloading:
 
 ```bash
 hirmos init /path/to/project --source /path/to/hirmos-framework.zip --integration agents
 ```
 
+Disable remote download and require an existing `_hirmos/` or local `--source`:
+
+```bash
+hirmos init --offline
+```
+
+## CLI update notice
+
+When `hirmos init` runs online, it checks whether a newer published HIRMOS CLI version is available on npm. If a newer version exists, the CLI prints a non-blocking message such as:
+
+```text
+A newer HIRMOS CLI is available: 1.3.2.
+Update with: npm install -g hirmos@latest
+```
+
+The notice does not stop initialization. Network failures, registry errors, or timeouts are ignored.
+
+Use `--offline` to disable both remote framework download and the update check. To disable only the update notice while keeping remote framework download available, run:
+
+```bash
+HIRMOS_CLI_UPDATE_CHECK=0 hirmos init
+```
+
 ## Supported integrations
 
 ```text
@@ -104,4 +136,4 @@ hirmos system-design
 hirmos implementation
 ```
 
-The CLI currently implements only `hirmos init`.
+The CLI implements `hirmos init`.

package/dist/commands/init.js

@@ -15,7 +15,11 @@ const validation_1 = require("../lib/validation");
 function runInit(options) {
     const projectRoot = path_1.default.resolve(options.projectPath);
     (0, validation_1.validateProjectRoot)(projectRoot);
-    (0, source_install_1.ensureHirmosInstalled)(projectRoot, options.source);
+    const installResult = (0, source_install_1.ensureHirmosInstalled)(projectRoot, {
+        source: options.source,
+        version: options.version,
+        offline: options.offline
+    });
     (0, validation_1.validateHirmosFramework)(projectRoot);
     const hirmosDir = path_1.default.join(projectRoot, "_hirmos");
     const registry = (0, integration_registry_1.loadRegistry)(hirmosDir);
@@ -38,12 +42,15 @@ function runInit(options) {
         (0, filesystem_1.writeText)(write.path, write.content);
     }
     (0, project_config_1.writeProjectConfig)(projectRoot, mergeResult.config);
-    return formatInitSummary(mergeResult.wasFirstInitialization, selected, mergeResult.added, mergeResult.alreadyInstalled, renderedWrites.map((item) => item.relative));
+    return formatInitSummary(mergeResult.wasFirstInitialization, selected, mergeResult.added, mergeResult.alreadyInstalled, renderedWrites.map((item) => item.relative), installResult);
 }
-function formatInitSummary(first, selected, added, alreadyInstalled, targets) {
+function formatInitSummary(first, selected, added, alreadyInstalled, targets, installResult) {
     const lines = [];
     if (first) {
         lines.push("HIRMOS initialized.", "");
+        if (installResult.installed && installResult.sourceDescription) {
+            lines.push(`Installed framework from ${installResult.sourceDescription}.`, "");
+        }
         lines.push("Installed integrations:");
         for (const id of selected)
             lines.push(`- ${id}`);

package/dist/index.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const args_1 = require("./lib/args");
 const errors_1 = require("./lib/errors");
 const init_1 = require("./commands/init");
+const update_notice_1 = require("./lib/update-notice");
 function main() {
     try {
         const parsed = (0, args_1.parseArgs)(process.argv.slice(2));
@@ -12,10 +13,19 @@ function main() {
             return;
         }
         if (parsed.command === "init") {
+            if (!parsed.offline) {
+                const updateNotice = (0, update_notice_1.getUpdateNotice)();
+                if (updateNotice)
+                    process.stderr.write(`${(0, update_notice_1.formatUpdateNotice)(updateNotice)}
+
+`);
+            }
             const summary = (0, init_1.runInit)({
                 projectPath: parsed.projectPath,
                 integrations: parsed.integrations,
-                source: parsed.source
+                source: parsed.source,
+                version: parsed.version,
+                offline: parsed.offline
             });
             process.stdout.write(summary);
             return;

package/dist/lib/args.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseArgs = parseArgs;
+exports.normalizeVersionOption = normalizeVersionOption;
 exports.parseIntegrationList = parseIntegrationList;
 exports.helpText = helpText;
 const path_1 = __importDefault(require("path"));
@@ -14,12 +15,14 @@ function parseArgs(argv) {
     }
     const command = argv[0];
     if (command !== "init") {
-        (0, errors_1.fail)(`Unsupported command: ${command}. DP-3B implements only: hirmos init`);
+        (0, errors_1.fail)(`Unsupported command: ${command}. This CLI currently supports: hirmos init`);
     }
     let projectPath = ".";
     let projectPathSet = false;
     let integrationValue;
     let source;
+    let version = "latest";
+    let offline = false;
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--integration") {
@@ -44,6 +47,21 @@ function parseArgs(argv) {
             source = arg.slice("--source=".length);
             continue;
         }
+        if (arg === "--version") {
+            const value = argv[++i];
+            if (!value)
+                (0, errors_1.fail)("Missing value for --version");
+            version = value;
+            continue;
+        }
+        if (arg.startsWith("--version=")) {
+            version = arg.slice("--version=".length);
+            continue;
+        }
+        if (arg === "--offline") {
+            offline = true;
+            continue;
+        }
         if (arg === "--help" || arg === "-h") {
             return { command: "help" };
         }
@@ -61,9 +79,17 @@ function parseArgs(argv) {
         command: "init",
         projectPath: path_1.default.resolve(projectPath),
         integrations,
-        source: source ? path_1.default.resolve(source) : undefined
+        source: source ? path_1.default.resolve(source) : undefined,
+        version: normalizeVersionOption(version),
+        offline
     };
 }
+function normalizeVersionOption(value) {
+    const normalized = value.trim();
+    if (!normalized)
+        (0, errors_1.fail)("--version must not be empty");
+    return normalized;
+}
 function parseIntegrationList(value) {
     const ids = value
         .split(",")
@@ -75,5 +101,5 @@ function parseIntegrationList(value) {
     return ids;
 }
 function helpText() {
-    return `HIRMOS CLI\n\nUsage:\n  hirmos init [project-path] [--integration <ids>] [--source <path>]\n\nDefaults:\n  project-path: .\n  integration: agents\n  source: existing _hirmos/ in the project\n\nDP-3B implements only hirmos init. Workflow commands such as hirmos requirements are interpreted by an agent after HIRMOS Core is loaded.\n`;
+    return `HIRMOS CLI\n\nUsage:\n  hirmos init [project-path] [--integration <ids>] [--source <path>] [--version <version>] [--offline]\n\nDefaults:\n  project-path: .\n  integration: agents\n  source: existing _hirmos/ in the project, otherwise the latest GitHub release\n  version: latest\n\nNotes:\n  --source installs from a local _hirmos folder, framework folder, or hirmos-framework.zip.\n  --version selects a GitHub release when _hirmos/ is missing and --source is not provided.\n  --offline disables remote release download and requires an existing _hirmos/ or --source.\n\nThis CLI implements hirmos init. Workflow commands such as hirmos requirements are interpreted by an agent after HIRMOS Core is loaded.\n`;
 }

package/dist/lib/source-install.js

@@ -4,20 +4,61 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureHirmosInstalled = ensureHirmosInstalled;
+exports.buildReleaseDownloadUrl = buildReleaseDownloadUrl;
+exports.normalizeReleaseVersion = normalizeReleaseVersion;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const errors_1 = require("./errors");
 const filesystem_1 = require("./filesystem");
-function ensureHirmosInstalled(projectRoot, source) {
+const RELEASE_OWNER = "ymarrerot";
+const RELEASE_REPO = "HIRMOS";
+const RELEASE_ASSET = "hirmos-framework.zip";
+function ensureHirmosInstalled(projectRoot, options) {
     const hirmosDir = path_1.default.join(projectRoot, "_hirmos");
     if ((0, filesystem_1.pathExists)(hirmosDir)) {
-        return;
+        return { installed: false, sourceDescription: null };
+    }
+    if (options.source) {
+        installFromSource(projectRoot, options.source);
+        return { installed: true, sourceDescription: options.source };
+    }
+    if (options.offline) {
+        (0, errors_1.fail)(`Missing _hirmos/ in ${projectRoot}. Offline mode requires an existing _hirmos/ or --source <path-to-hirmos-framework.zip-or-folder>.`);
     }
-    if (!source) {
-        (0, errors_1.fail)(`Missing _hirmos/ in ${projectRoot}. Provide --source <path-to-hirmos-framework.zip-or-folder>.`);
+    const version = normalizeReleaseVersion(options.version);
+    const url = buildReleaseDownloadUrl(version);
+    const tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "hirmos-release-"));
+    const zipPath = path_1.default.join(tmp, RELEASE_ASSET);
+    try {
+        downloadFile(url, zipPath);
+        installFromZip(projectRoot, zipPath);
+        return { installed: true, sourceDescription: version === "latest" ? "latest GitHub release" : `GitHub release ${version}` };
     }
+    finally {
+        fs_1.default.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+function buildReleaseDownloadUrl(version) {
+    const normalized = normalizeReleaseVersion(version);
+    const overrideBase = process.env.HIRMOS_CLI_RELEASE_BASE_URL;
+    if (overrideBase) {
+        const trimmed = overrideBase.replace(/\/+$/u, "");
+        return `${trimmed}/${normalized}/${RELEASE_ASSET}`;
+    }
+    if (normalized === "latest") {
+        return `https://github.com/${RELEASE_OWNER}/${RELEASE_REPO}/releases/latest/download/${RELEASE_ASSET}`;
+    }
+    return `https://github.com/${RELEASE_OWNER}/${RELEASE_REPO}/releases/download/${normalized}/${RELEASE_ASSET}`;
+}
+function normalizeReleaseVersion(version) {
+    const trimmed = version.trim();
+    if (!trimmed || trimmed === "latest")
+        return "latest";
+    return trimmed.startsWith("v") ? trimmed : `v${trimmed}`;
+}
+function installFromSource(projectRoot, source) {
     if (!(0, filesystem_1.pathExists)(source)) {
         (0, errors_1.fail)(`Source path does not exist: ${source}`);
     }
@@ -46,11 +87,11 @@ function installFromZip(projectRoot, zipPath) {
             extractZip(zipPath, tmp);
         }
         catch (error) {
-            (0, errors_1.fail)(`Unable to extract --source zip. Ensure the zip is valid and an extraction command is available: ${error.message}`);
+            (0, errors_1.fail)(`Unable to extract framework zip. Ensure the zip is valid and an extraction command is available: ${error.message}`);
         }
         const sourceHirmos = findHirmosDir(tmp);
         if (!sourceHirmos) {
-            (0, errors_1.fail)(`Source zip does not contain an _hirmos/ folder: ${zipPath}`);
+            (0, errors_1.fail)(`Framework zip does not contain an _hirmos/ folder: ${zipPath}`);
         }
         copyHirmos(projectRoot, sourceHirmos);
     }
@@ -79,6 +120,16 @@ function copyHirmos(projectRoot, sourceHirmos) {
     }
     (0, filesystem_1.ensureDir)(projectRoot);
     fs_1.default.cpSync(sourceHirmos, target, { recursive: true, errorOnExist: true });
+    validateCopiedHirmos(projectRoot);
+}
+function validateCopiedHirmos(projectRoot) {
+    const required = ["_hirmos/HIRMOS_CORE.md", "_hirmos/VERSION", "_hirmos/project.json"];
+    for (const relative of required) {
+        if (!(0, filesystem_1.pathExists)(path_1.default.join(projectRoot, relative))) {
+            fs_1.default.rmSync(path_1.default.join(projectRoot, "_hirmos"), { recursive: true, force: true });
+            (0, errors_1.fail)(`Installed framework is incomplete; missing ${relative}. Removed partial _hirmos/ install.`);
+        }
+    }
 }
 function extractZip(zipPath, destination) {
     if (process.platform === "win32") {
@@ -87,3 +138,26 @@ function extractZip(zipPath, destination) {
     }
     (0, child_process_1.execFileSync)("unzip", ["-q", zipPath, "-d", destination], { stdio: "ignore" });
 }
+function downloadFile(url, destination) {
+    (0, filesystem_1.ensureDir)(path_1.default.dirname(destination));
+    try {
+        if (process.platform === "win32") {
+            (0, child_process_1.execFileSync)("powershell", [
+                "-NoProfile",
+                "-Command",
+                "$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -Uri $args[0] -OutFile $args[1]",
+                url,
+                destination
+            ], { stdio: "ignore" });
+        }
+        else {
+            (0, child_process_1.execFileSync)("curl", ["-fL", "--retry", "2", "--connect-timeout", "20", "--max-time", "120", "-o", destination, url], { stdio: "ignore" });
+        }
+    }
+    catch (error) {
+        (0, errors_1.fail)(`Unable to download HIRMOS release from ${url}. Use --source for a local release package or --offline to disable downloads. ${error.message}`);
+    }
+    if (!(0, filesystem_1.pathExists)(destination) || fs_1.default.statSync(destination).size === 0) {
+        (0, errors_1.fail)(`Downloaded HIRMOS release is empty or missing: ${destination}`);
+    }
+}

package/dist/lib/update-notice.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInstalledCliVersion = getInstalledCliVersion;
+exports.normalizeSemver = normalizeSemver;
+exports.compareSemver = compareSemver;
+exports.buildUpdateNotice = buildUpdateNotice;
+exports.formatUpdateNotice = formatUpdateNotice;
+exports.getLatestPublishedVersion = getLatestPublishedVersion;
+exports.getUpdateNotice = getUpdateNotice;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const PACKAGE_NAME = "hirmos";
+const DEFAULT_TIMEOUT_MS = 1500;
+const ANSI_BOLD = "\u001b[1m";
+const ANSI_YELLOW = "\u001b[33m";
+const ANSI_RESET = "\u001b[0m";
+function getInstalledCliVersion(cliRoot = path_1.default.resolve(__dirname, "../..")) {
+    try {
+        const packageJsonPath = path_1.default.join(cliRoot, "package.json");
+        const raw = fs_1.default.readFileSync(packageJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === "string" && parsed.version.trim() ? parsed.version.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeSemver(value) {
+    return value.trim().replace(/^v/u, "").split("-")[0];
+}
+function compareSemver(left, right) {
+    const leftParts = normalizeSemver(left).split(".").map((part) => Number.parseInt(part, 10));
+    const rightParts = normalizeSemver(right).split(".").map((part) => Number.parseInt(part, 10));
+    for (let i = 0; i < 3; i += 1) {
+        const leftValue = Number.isFinite(leftParts[i]) ? leftParts[i] : 0;
+        const rightValue = Number.isFinite(rightParts[i]) ? rightParts[i] : 0;
+        if (leftValue > rightValue)
+            return 1;
+        if (leftValue < rightValue)
+            return -1;
+    }
+    return 0;
+}
+function buildUpdateNotice(currentVersion, latestVersion) {
+    if (!currentVersion || !latestVersion)
+        return null;
+    if (compareSemver(latestVersion, currentVersion) <= 0)
+        return null;
+    return `A newer HIRMOS CLI is available: ${latestVersion}.\nUpdate with: npm install -g ${PACKAGE_NAME}@latest`;
+}
+function formatUpdateNotice(message, useColor = Boolean(process.stderr.isTTY) && process.env.NO_COLOR === undefined) {
+    return useColor ? `${ANSI_BOLD}${ANSI_YELLOW}${message}${ANSI_RESET}` : message;
+}
+function getLatestPublishedVersion(timeoutMs = DEFAULT_TIMEOUT_MS) {
+    if (process.env.HIRMOS_CLI_UPDATE_CHECK === "0" || process.env.HIRMOS_NO_UPDATE_CHECK === "1") {
+        return null;
+    }
+    try {
+        const result = (0, child_process_1.spawnSync)("npm", ["view", PACKAGE_NAME, "version", "--silent"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: timeoutMs
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        const version = String(result.stdout ?? "").trim();
+        return /^v?\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/u.test(version) ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function getUpdateNotice() {
+    return buildUpdateNotice(getInstalledCliVersion(), getLatestPublishedVersion());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hirmos",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "HIRMOS product-facing CLI.",
   "license": "Apache-2.0",
   "type": "commonjs",