@xhulz/nina 0.39.0 → 0.40.0

package/src/paths.mjs

@@ -9,6 +9,7 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 
@@ -101,6 +102,70 @@ export function legacyHint(target) {
     : '';
 }
 
+/**
+ * A project's profile, read the one way every command reads it: `{profile, path}`, or `{path, error}` — one
+ * line saying what is wrong, with `missing` when there is no profile at all. Commands that parsed it on
+ * their own answered a stray comma with a stack trace, and each that did not said so differently.
+ *
+ * @param {string} target - The project.
+ * @returns {{path: string, profile?: object, error?: string, missing?: boolean}}
+ */
+export function readProfile(target) {
+  const path = join(target, HARNESS, 'profile.json');
+  if (!existsSync(path)) {
+    const hint = legacyHint(target) || ' — run `nina init` first, or name the project with --project';
+    return { path, missing: true, error: `no ${HARNESS}/profile.json under ${target}${hint}` };
+  }
+  try {
+    const profile = JSON.parse(readFileSync(path, 'utf8'));
+    if (profile === null || typeof profile !== 'object' || Array.isArray(profile)) return { path, error: `${path} is not a JSON object` };
+    return { path, profile };
+  } catch (error) {
+    return { path, error: `${path} cannot be read — ${error.message}` };
+  }
+}
+
+/**
+ * Where a project's layers are read from.
+ *
+ * A project pins a frozen release, or tracks the working tree with "dev". A pinned release
+ * that is missing is an error, never a silent fall back to whatever the harness happens to
+ * look like right now: that would compose an unreviewed core into a project that asked for
+ * a reviewed one, and nothing downstream would say so. Every reader asks this one: the commands,
+ * and the hooks that ask whether the pin ships them.
+ *
+ * @param {string} root - The NINA install directory.
+ * @param {string|undefined} core - The profile's `core` field.
+ * @returns {{dir: string}|{error: string}}
+ */
+export function layerRootFor(root, core) {
+  if (!core || core === 'dev') {
+    // `dev` means "track the layers as they are being worked on", which only exists in a
+    // checkout of this repo. An installed package ships frozen releases and nothing else,
+    // so say that rather than composing an empty tree and reporting nothing wrong.
+    if (!existsSync(join(root, 'core'))) {
+      return { error: `profile pins core "dev", which tracks the NINA working tree — ${root} is an installed package and has only releases` };
+    }
+    return { dir: root };
+  }
+  // A name, never a path: `../x` would read layers from outside the releases.
+  if (typeof core !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(core)) return { error: `profile pins core ${JSON.stringify(core)}, which is not a release name` };
+  const dir = join(root, 'releases', core);
+  if (!existsSync(dir)) return { error: `profile pins core ${core}, which is not in ${join(root, 'releases')}` };
+  return { dir };
+}
+
+/**
+ * The surfaces a layer root offers, by name, in order. Seven commands listed the directory each on its own.
+ *
+ * @param {string} layerRoot - From {@link layerRootFor}.
+ * @returns {Promise<string[]>}
+ */
+export async function surfacesIn(layerRoot) {
+  const entries = await readdir(join(layerRoot, 'surfaces'), { withFileTypes: true }).catch(() => []);
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+
 /**
  * Where `nina upgrade --apply` writes down a move while it is in flight: the versions it moves between, the
  * files it composes for the first time, and — under {@link movedFrom} — every file it can touch, as it was.

package/src/shell.mjs

@@ -13,8 +13,9 @@ import { spawnSync } from 'node:child_process';
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
-import { PINK, printBanner, useColor } from './banner.mjs';
+import { printBanner } from './banner.mjs';
 import { shellHistoryFile } from './paths.mjs';
+import { dim, pink } from './look.mjs';
 
 /** Words the session answers itself rather than handing to a command. */
 const LEAVE = new Set(['exit', 'quit', 'q']);
@@ -87,8 +88,7 @@ function keep(line) {
  */
 export function shell({ bin, version, commands }) {
   const terminal = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-  const dim = (s) => (useColor() ? `\x1b[2m${s}\x1b[0m` : s);
-  const prompt = useColor() ? `\x1b[38;2;${PINK.join(';')}mnina ›\x1b[0m ` : 'nina › ';
+  const prompt = `${pink('nina ›')} `;
 
   printBanner(version);
   console.log(dim('  type a command — stats, check, upgrade --to <version> — `help` lists them, `clear` starts the screen over, `exit` leaves\n'));

package/src/steps.mjs

@@ -6,16 +6,13 @@
  * project forward was six commands in a fixed order, where getting the order wrong quietly
  * overwrote the project's own file — so the order belongs in the tool, not in a message.
  *
- * The animation is a convenience, not the contract: a step reports the same text either way,
- * so a log, a CI run and a pipe all read like the terminal does minus the dots.
+ * On a terminal the step running shows as `...` until its line replaces it. Not animated: a step runs
+ * synchronously, so a timer would never fire while it works. A log, a CI run and a pipe read like the
+ * terminal does, minus that line.
  */
 
-/** Frames of the ellipsis, slow enough to read and fast enough to look alive. */
-const FRAMES = ['.  ', '.. ', '...'];
-const TICK = 220;
-
 /**
- * Whether to animate — a pipe, a CI log and a test all get plain lines instead.
+ * Whether to show the step running — a pipe, a CI log and a test all get plain lines instead.
  *
  * @param {NodeJS.WriteStream} stream
  * @returns {boolean}
@@ -46,24 +43,13 @@ export function runSteps(steps, options = {}) {
       continue;
     }
 
-    let frame = 0;
-    let timer = null;
-    if (live) {
-      stream.write(`  ${FRAMES[0]} ${step.label}`);
-      timer = setInterval(() => {
-        frame = (frame + 1) % FRAMES.length;
-        stream.write(`\r  ${FRAMES[frame]} ${step.label}`);
-      }, TICK);
-      timer.unref?.();
-    }
-
+    if (live) stream.write(`  ... ${step.label}`);
     let result;
     try {
       result = step.run();
     } catch (error) {
       result = { ok: false, log: String(error?.stack ?? error) };
     } finally {
-      if (timer) clearInterval(timer);
       // `\r` alone leaves the tail of the longest line behind when the next one is shorter.
       if (live) stream.write('\r\u001b[K');
     }

package/src/store.mjs

@@ -21,7 +21,7 @@ const UNREAD = new Set(['UNCLEAR', 'NONE', null, undefined]);
  * @param {string} text - The file.
  * @returns {object[]}
  */
-export function parseStore(text) {
+function parseStore(text) {
   return String(text)
     .split('\n')
     .filter((l) => l.trim())
@@ -74,7 +74,7 @@ export function readStoreFile(file, { raw = false } = {}) {
  * @param {string} dir - The project.
  * @returns {string[]}
  */
-export function storeNamesOf(dir) {
+function storeNamesOf(dir) {
   const names = new Set([slugFor(dir)]);
   try {
     names.add(slugFor(realpathSync(dir)));

package/src/wiring.mjs

@@ -22,11 +22,11 @@ import { join } from 'node:path';
 /** The composed scripts the hooks run. */
 export const CHECK = 'scripts/harness-check.mjs';
 export const GATE = 'scripts/loop-gate.mjs';
-export const GUARD = 'scripts/edit-guard.mjs';
-export const COST = 'scripts/cost-watch.mjs';
+const GUARD = 'scripts/edit-guard.mjs';
+const COST = 'scripts/cost-watch.mjs';
 
 /** The npm scripts the detectors hang off: the reviewer runs one, the other is a detector itself. */
-export const SCRIPTS = {
+const SCRIPTS = {
   'harness:check': 'node scripts/harness-check.mjs',
   'harness:compose:check': 'nina compose --check --quiet',
 };
@@ -73,7 +73,7 @@ export function packageInstalled(target) {
  * @param {string} module - `gate`, `guard`, …
  * @returns {boolean}
  */
-export function packageExports(target, module) {
+function packageExports(target, module) {
   try {
     createRequire(join(target, 'package.json')).resolve(`@xhulz/nina/${module}`);
     return true;
@@ -111,7 +111,7 @@ const previousCommands = (h) => [command(h.script, h.mode), ...EARLIER_CANNOT_ST
  * loop gate has four, one per fact it keeps: a verdict, a dispatch, the owner speaking, and the
  * decision itself; and a fifth, as each stage starts, that hands the stage its lessons (`src/lessons.mjs`).
  */
-export const HOOKS = [
+const HOOKS = [
   {
     event: 'Stop', script: CHECK, mode: '--hook', timeout: 30, statusMessage: 'Checking the harness...', why: 'nobody is told what a turn left behind',
     crash: (cannot) => ({ systemMessage: `NINA: the harness check could not start — ${cannot}` }),
@@ -308,6 +308,17 @@ function settingsHooks(hooks) {
   return out;
 }
 
+/** How {@link missingWiring} opens the sentence that says the package is missing. */
+const NOT_INSTALLED = '@xhulz/nina is not installed in this project';
+
+/**
+ * Whether what {@link missingWiring} found includes the package itself: the one thing `wire` cannot do.
+ *
+ * @param {string[]} unwired - Its sentences.
+ * @returns {boolean}
+ */
+export const lacksPackage = (unwired) => unwired.some((w) => w.startsWith(NOT_INSTALLED));
+
 /**
  * Whatever of the wiring a project lacks, one sentence each.
  *
@@ -320,7 +331,7 @@ export async function missingWiring(target, shipped) {
   // First, because nothing below matters without it: the composed scripts import the package.
   if ((shipped.has(CHECK) || shipped.has(GATE) || shipped.has(GUARD)) && !packageInstalled(target)) {
     out.push(
-      '@xhulz/nina is not installed in this project, so the composed scripts cannot load and every hook fails — ' +
+      `${NOT_INSTALLED}, so the composed scripts cannot load and every hook fails — ` +
         'pnpm add -D -E @xhulz/nina',
     );
   } else {