archik 0.6.3 → 0.6.4

package/bin/archik.js

@@ -13,9 +13,16 @@
  * where its install lives.
  */
 import { spawnSync } from "node:child_process";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { existsSync, realpathSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
 
 const here = dirname(realpathSync(fileURLToPath(import.meta.url)));
 const pkgRoot = resolve(here, "..");
@@ -24,6 +31,14 @@ const env = { ...process.env, ARCHIK_PKG_ROOT: pkgRoot };
 
 const distEntry = resolve(pkgRoot, "dist", "cli", "archik.mjs");
 
+// First-run / new-version banner. We can't reliably print on `npm
+// install` itself — npm 10+ silences postinstall stdout/stderr by
+// default unless --foreground-scripts is passed. So we print on
+// the first archik invocation after install or upgrade, and stamp
+// a marker file so the next call stays quiet. Honours NO_COLOR /
+// ARCHIK_NO_BANNER and stays silent when stdout isn't a TTY.
+maybePrintFirstRunBanner();
+
 let result;
 if (existsSync(distEntry)) {
   result = spawnSync(process.execPath, [distEntry, ...args], {
@@ -56,3 +71,70 @@ if (existsSync(distEntry)) {
 }
 
 process.exit(result.status ?? 1);
+
+function maybePrintFirstRunBanner() {
+  if (
+    process.env["ARCHIK_NO_BANNER"] !== undefined ||
+    process.env["CI"] !== undefined ||
+    !process.stdout.isTTY
+  ) {
+    return;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(resolve(pkgRoot, "package.json"), "utf8"));
+  } catch {
+    return;
+  }
+  const version = String(pkg.version ?? "");
+  if (version === "") return;
+
+  const markerDir = join(homedir(), ".archik");
+  const markerFile = join(markerDir, "last-banner-version");
+  let lastSeen = "";
+  try {
+    lastSeen = readFileSync(markerFile, "utf8").trim();
+  } catch {
+    // first install — no marker yet
+  }
+  if (lastSeen === version) return;
+
+  // Show the banner and persist the version. Failure to persist is
+  // non-fatal — the banner just shows again next call.
+  printBanner(version);
+  try {
+    mkdirSync(markerDir, { recursive: true });
+    writeFileSync(markerFile, version + "\n");
+  } catch {
+    // read-only home or similar — fine
+  }
+}
+
+function printBanner(version) {
+  const colour = process.env["NO_COLOR"] === undefined;
+  const c = (open, close) => (s) =>
+    colour ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+  const bold = c("1", "22");
+  const dim = c("2", "22");
+  const cyan = c("36", "39");
+  const green = c("32", "39");
+  const magenta = c("35", "39");
+  const line = dim("─".repeat(56));
+  const tick = bold(green("✓"));
+  const arrow = cyan("▸");
+
+  process.stdout.write(
+    [
+      "",
+      line,
+      `  ${tick} ${bold(magenta("archik"))} ${dim("v" + version)} ${dim("ready")}`,
+      line,
+      `  ${arrow} ${bold("archik init")}   ${dim("scaffold .archik/main.archik.yaml")}`,
+      `  ${arrow} ${bold("archik dev")}    ${dim("open the live canvas in your browser")}`,
+      `  ${arrow} ${bold("archik --help")} ${dim("full command list")}`,
+      "",
+      `  ${dim("Docs: https://npmjs.com/package/archik")}`,
+      "",
+    ].join("\n") + "\n",
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archik",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Architecture diagrams as YAML. Live canvas in the browser, headless SVG render in CI, and an installable Claude skill so the model edits the same file you do.",
   "keywords": [
     "architecture",
@@ -38,7 +38,6 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "archik": "tsx --tsconfig tsconfig.app.json src/cli/index.ts",
-    "postinstall": "node bin/postinstall.js || true",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "devDependencies": {

package/bin/postinstall.js

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-/**
- * Friendly post-install banner. npm 10+ stopped echoing the package
- * version ("added 1 package in 3s" is all the user sees), so this
- * gives them a confirmation, the version they got, and where to go
- * next. Stays quiet under CI / non-TTY / inside a parent npm install
- * so it doesn't pollute logs.
- */
-import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-// Skip when noise would hurt more than help.
-if (
-  process.env["CI"] !== undefined ||
-  process.env["ARCHIK_NO_BANNER"] !== undefined ||
-  !process.stdout.isTTY ||
-  // Inside `npm install` / yarn / pnpm of a host project — only
-  // show the banner for global installs and direct local installs.
-  process.env["npm_config_global"] !== "true" &&
-    process.env["npm_command"] === "install" &&
-    process.env["npm_config_save"] !== undefined
-) {
-  process.exit(0);
-}
-
-const here = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(
-  readFileSync(resolve(here, "..", "package.json"), "utf8"),
-);
-
-const enabled = process.env["NO_COLOR"] === undefined;
-const c = (open, close) => (s) =>
-  enabled ? `\x1b[${open}m${s}\x1b[${close}m` : s;
-const bold = c("1", "22");
-const dim = c("2", "22");
-const cyan = c("36", "39");
-const green = c("32", "39");
-const magenta = c("35", "39");
-
-const line = dim("─".repeat(56));
-const tick = bold(green("✓"));
-const arrow = cyan("▸");
-
-process.stdout.write(
-  [
-    "",
-    line,
-    `  ${tick} ${bold(magenta("archik"))} ${dim("v" + pkg.version)} ${dim("installed")}`,
-    line,
-    `  ${arrow} ${bold("archik init")}   ${dim("scaffold .archik/main.archik.yaml")}`,
-    `  ${arrow} ${bold("archik dev")}    ${dim("open the live canvas in your browser")}`,
-    `  ${arrow} ${bold("archik --help")} ${dim("full command list")}`,
-    "",
-    `  ${dim("Docs: https://npmjs.com/package/archik")}`,
-    "",
-  ].join("\n"),
-);