@nemus-cli/nemus 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-01
+
+### Changed
+
+- **First-time setup now runs right after install.** On a fresh `npm install -g`
+  in an interactive terminal, the postinstall step launches `nemus configure`
+  automatically (it installs the shell integration + optional MCP server and
+  prints the activation reminder) instead of only suggesting you run it. It runs
+  **only on a first install** (skipped once `~/.nemus/config.json` exists, so
+  upgrades never re-prompt) and **only when a controlling terminal is reachable**
+  (via `/dev/tty`, since npm pipes postinstall stdio) — piped/scripted/CI installs,
+  or `NEMUS_SKIP_CONFIGURE=1`, fall back to the previous non-interactive path
+  (shell integration + a printed tip), so an install can never hang.
+
+## [0.3.3] - 2026-08-30
+
+### Added
+
+- **`reflect --workspace <name>`** — analyze a single workspace by name (ignores
+  `--limit`); a clean error if that workspace has no recent Claude/pi session.
+- **`reflect` now saves each report** as timestamped JSON under
+  `~/.nemus/reflect/` (scope suffix for single-workspace runs), so runs can be
+  revisited or diffed over time. Best-effort (never fails the run); disable with
+  **`--no-save`**. The path is printed after a run (and included as `savedTo` in
+  `--json`).
+
 ## [0.3.2] - 2026-08-30
 
 ### Fixed

package/dist/commands/reflect.js

@@ -13,9 +13,11 @@ function registerReflectCommand(parent) {
         .alias('retro')
         .description('Analyze your recent workspace sessions and suggest skill/prompt/context improvements (LLM-as-a-judge)')
         .option('-n, --limit <n>', 'How many recent workspaces to analyze', '10')
+        .option('-w, --workspace <name>', 'Analyze a single workspace by name (ignores --limit)')
         .option('--model <model>', 'Judge model override (agent-native pattern/id)')
         .option('--thinking <level>', 'Judge thinking level for pi: off|minimal|low|medium|high|xhigh|max')
         .option('--json', 'Output the report as JSON')
+        .option('--no-save', 'Do not save the report to ~/.nemus/reflect/')
         .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
         .action(async (opts) => {
         await handleReflect(opts);
@@ -26,9 +28,13 @@ async function handleReflect(opts) {
     try {
         const showProgress = !opts.json && !opts.dryRun;
         if (showProgress) {
-            (0, logger_1.logStep)(`Analyzing your ${(0, colors_1.colorize)(String(limit), 'cyan')} most recent workspaces…`);
+            (0, logger_1.logStep)(opts.workspace
+                ? `Analyzing workspace ${(0, colors_1.colorize)(opts.workspace, 'cyan')}…`
+                : `Analyzing your ${(0, colors_1.colorize)(String(limit), 'cyan')} most recent workspaces…`);
         }
-        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit, showProgress ? printProgress : undefined);
+        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit, showProgress ? printProgress : undefined, {
+            workspace: opts.workspace,
+        });
         const withSessions = corpus.workspaces.filter((w) => w.session).length;
         // A script does the heavy analysis (clustering failures, counting tools,
         // spotting correction loops); the LLM only ever sees these compact facts,
@@ -45,7 +51,9 @@ async function handleReflect(opts) {
             return;
         }
         if (withSessions === 0) {
-            const msg = 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
+            const msg = opts.workspace
+                ? `No recent agent session found for workspace "${opts.workspace}" (need a Claude/pi transcript).`
+                : 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
             if (opts.json)
                 (0, output_1.outputJsonError)(msg);
             else
@@ -69,11 +77,27 @@ async function handleReflect(opts) {
             stopSpinner();
         }
         const report = (0, reflect_1.parseReflectionReport)(parsed);
+        // Persist the report (best-effort; never fails the run) unless --no-save.
+        let savedTo;
+        if (opts.save !== false) {
+            try {
+                savedTo = await (0, reflect_1.saveReflectionReport)(report, {
+                    analyzed: withSessions,
+                    workspaces: corpus.workspaces.length,
+                    workspace: opts.workspace,
+                });
+            }
+            catch {
+                /* saving is a convenience, not the point */
+            }
+        }
         if (opts.json) {
-            (0, output_1.outputJson)({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report });
+            (0, output_1.outputJson)({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report, savedTo });
             return;
         }
         printReport(report, corpus.workspaces.length, withSessions);
+        if (savedTo)
+            (0, logger_1.logInfo)(`Saved report to ${(0, colors_1.colorize)(savedTo, 'dim')}`);
     }
     catch (error) {
         const msg = error instanceof Error ? error.message : 'reflect failed';

package/dist/utils/reflect.js

@@ -33,15 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REFLECT_SCHEMA = void 0;
+exports.REFLECT_REPORTS_DIR = exports.REFLECT_SCHEMA = void 0;
 exports.isCorrectionPrompt = isCorrectionPrompt;
 exports.distillTranscript = distillTranscript;
 exports.classifyAgentsMd = classifyAgentsMd;
 exports.findLatestTranscriptFile = findLatestTranscriptFile;
 exports.gatherReflectionCorpus = gatherReflectionCorpus;
 exports.parseReflectionReport = parseReflectionReport;
+exports.saveReflectionReport = saveReflectionReport;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
+const config_1 = require("./config");
 const workspace_meta_1 = require("./workspace-meta");
 const agent_config_1 = require("./agent-config");
 const claude_sessions_1 = require("./claude-sessions");
@@ -307,14 +309,17 @@ async function contextFilesFor(workspacePath) {
  * session, plus the globally-available skills. `onProgress` (optional) fires
  * once per workspace as it finishes, for a live progress display.
  */
-async function gatherReflectionCorpus(limit, onProgress) {
+async function gatherReflectionCorpus(limit, onProgress, opts = {}) {
     const [sessions, workspaces, availableSkills] = await Promise.all([
         (0, claude_sessions_1.getWorkspaceSessions)(), // already sorted by last-active, one per workspace
         (0, workspace_meta_1.listWorkspaces)(false),
         listAvailableSkills(),
     ]);
     const metaByName = new Map(workspaces.map((w) => [w.name, w]));
-    const recent = sessions.slice(0, limit);
+    // A single named workspace (ignores limit), else the N most recently active.
+    const recent = opts.workspace
+        ? sessions.filter((s) => s.workspaceName === opts.workspace)
+        : sessions.slice(0, limit);
     const digests = [];
     for (let index = 0; index < recent.length; index++) {
         const s = recent[index];
@@ -387,3 +392,19 @@ function parseReflectionReport(parsed) {
         .filter((r) => r !== null);
     return { summary, recommendations };
 }
+// -------------------------------------------------------------- report saving
+/** Where saved reflection reports live: `~/.nemus/reflect/`. */
+exports.REFLECT_REPORTS_DIR = path.join(config_1.CACHE_DIR, 'reflect');
+/**
+ * Persist a reflection report as timestamped JSON under `~/.nemus/reflect/`, so
+ * a run can be revisited or diffed over time. Returns the written path. Pure
+ * side-effect (mkdir -p + write); callers treat failure as non-fatal.
+ */
+async function saveReflectionReport(report, meta) {
+    await fs.mkdir(exports.REFLECT_REPORTS_DIR, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const scope = meta.workspace ? `-${meta.workspace.replace(/[^a-zA-Z0-9_-]+/g, '_')}` : '';
+    const file = path.join(exports.REFLECT_REPORTS_DIR, `${stamp}${scope}.json`);
+    await fs.writeFile(file, JSON.stringify({ generatedAt: new Date().toISOString(), ...meta, ...report }, null, 2));
+    return file;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "workspaces": [
     "packages/*"
   ],

package/scripts/postinstall.js

@@ -12,8 +12,9 @@
 
 'use strict';
 
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
 // Skip in CI environments
@@ -21,6 +22,72 @@ if (process.env.CI) process.exit(0);
 
 const PKG_ROOT = path.join(__dirname, '..');
 const SHELL_SCRIPT = path.join(PKG_ROOT, 'install-shell-integration.sh');
+const CLI_BIN = path.join(PKG_ROOT, 'bin', 'workspace.js');
+
+// ── First-time interactive setup ─────────────────────────────────────────────
+// On a FRESH install, run `nemus configure` right away so setup happens after
+// install instead of the user having to remember to. `configure` is a superset
+// of this script's work — it installs the shell integration + (optionally) the
+// MCP server and prints the source reminder — so on success we exit here.
+//
+// npm runs postinstall with stdio PIPED (not a TTY) unless `--foreground-scripts`
+// is set, so we can't gate on process.std*.isTTY (it's falsy during a normal
+// `npm i -g`, so the prompt would never fire). Instead we reach the controlling
+// terminal directly via /dev/tty — openable during an interactive install even
+// though npm piped our own stdio — and wire configure's stdio to it. With no
+// controlling terminal (piped/scripted installs) the open fails and we fall
+// through to the non-interactive tip path, so an install can never hang.
+function cacheDir() {
+  return (
+    process.env.NEMUS_CACHE_DIR ||
+    process.env.WORKSPACE_MANAGER_CACHE_DIR ||
+    path.join(os.homedir(), '.nemus')
+  );
+}
+
+// NEMUS_SKIP_CONFIGURE opts out — but only for real values: `0`/`false`/empty do
+// NOT skip (a user setting `=0` means "don't skip").
+function optedOut() {
+  const v = (process.env.NEMUS_SKIP_CONFIGURE || '').trim().toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false';
+}
+
+// The config marker `configure` writes (utils/config.ts: saveUserConfig ->
+// <NEMUS_CACHE_DIR|WORKSPACE_MANAGER_CACHE_DIR|~/.nemus>/config.json). Same
+// precedence as here, so its presence reliably means "already configured".
+function alreadyConfigured() {
+  return fs.existsSync(path.join(cacheDir(), 'config.json'));
+}
+
+// A read/write fd on the controlling terminal, or null if there isn't one.
+function openControllingTty() {
+  if (process.platform === 'win32') return null; // no /dev/tty; shell integration is bash/zsh anyway
+  try {
+    return fs.openSync('/dev/tty', 'r+');
+  } catch {
+    return null;
+  }
+}
+
+if (!optedOut() && fs.existsSync(CLI_BIN) && !alreadyConfigured()) {
+  const tty = openControllingTty();
+  if (tty !== null) {
+    try {
+      // argv form (no shell) so an odd package path with quotes/$/backticks is
+      // safe; stdio wired to the real terminal so inquirer can prompt.
+      // process.execPath (not 'node') — node may not be on PATH during a
+      // lifecycle script (nvm/Windows), and an ENOENT here would be swallowed by
+      // the catch, silently skipping configure in the very case this targets.
+      execFileSync(process.execPath, [CLI_BIN, 'configure'], { stdio: [tty, tty, tty] });
+      fs.closeSync(tty);
+      process.exit(0); // configure handled shell integration + reminder
+    } catch {
+      try { fs.closeSync(tty); } catch { /* ignore */ }
+      // Canceled / failed — fall through to the standard setup + tip below so the
+      // install still leaves things in a working state.
+    }
+  }
+}
 
 const shell = process.env.SHELL || '';
 const shellType = shell.endsWith('/zsh') ? 'zsh'

package/src/commands/reflect.ts

@@ -5,6 +5,7 @@ import { colorize } from '../utils/colors';
 import {
   gatherReflectionCorpus,
   parseReflectionReport,
+  saveReflectionReport,
   REFLECT_SCHEMA,
   ReflectionReport,
   ReflectProgress,
@@ -19,24 +20,40 @@ export function registerReflectCommand(parent: Command) {
     .alias('retro')
     .description('Analyze your recent workspace sessions and suggest skill/prompt/context improvements (LLM-as-a-judge)')
     .option('-n, --limit <n>', 'How many recent workspaces to analyze', '10')
+    .option('-w, --workspace <name>', 'Analyze a single workspace by name (ignores --limit)')
     .option('--model <model>', 'Judge model override (agent-native pattern/id)')
     .option('--thinking <level>', 'Judge thinking level for pi: off|minimal|low|medium|high|xhigh|max')
     .option('--json', 'Output the report as JSON')
+    .option('--no-save', 'Do not save the report to ~/.nemus/reflect/')
     .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
     .action(async (opts) => {
       await handleReflect(opts);
     });
 }
 
-async function handleReflect(opts: { limit?: string; model?: string; thinking?: string; json?: boolean; dryRun?: boolean }) {
+async function handleReflect(opts: {
+  limit?: string;
+  workspace?: string;
+  model?: string;
+  thinking?: string;
+  json?: boolean;
+  save?: boolean; // commander sets `save: false` for --no-save
+  dryRun?: boolean;
+}) {
   const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
   try {
     const showProgress = !opts.json && !opts.dryRun;
     if (showProgress) {
-      logStep(`Analyzing your ${colorize(String(limit), 'cyan')} most recent workspaces…`);
+      logStep(
+        opts.workspace
+          ? `Analyzing workspace ${colorize(opts.workspace, 'cyan')}…`
+          : `Analyzing your ${colorize(String(limit), 'cyan')} most recent workspaces…`,
+      );
     }
 
-    const corpus = await gatherReflectionCorpus(limit, showProgress ? printProgress : undefined);
+    const corpus = await gatherReflectionCorpus(limit, showProgress ? printProgress : undefined, {
+      workspace: opts.workspace,
+    });
     const withSessions = corpus.workspaces.filter((w) => w.session).length;
     // A script does the heavy analysis (clustering failures, counting tools,
     // spotting correction loops); the LLM only ever sees these compact facts,
@@ -54,7 +71,9 @@ async function handleReflect(opts: { limit?: string; model?: string; thinking?:
     }
 
     if (withSessions === 0) {
-      const msg = 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
+      const msg = opts.workspace
+        ? `No recent agent session found for workspace "${opts.workspace}" (need a Claude/pi transcript).`
+        : 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
       if (opts.json) outputJsonError(msg);
       else logError(msg);
       process.exit(1);
@@ -77,11 +96,26 @@ async function handleReflect(opts: { limit?: string; model?: string; thinking?:
     }
     const report = parseReflectionReport(parsed);
 
+    // Persist the report (best-effort; never fails the run) unless --no-save.
+    let savedTo: string | undefined;
+    if (opts.save !== false) {
+      try {
+        savedTo = await saveReflectionReport(report, {
+          analyzed: withSessions,
+          workspaces: corpus.workspaces.length,
+          workspace: opts.workspace,
+        });
+      } catch {
+        /* saving is a convenience, not the point */
+      }
+    }
+
     if (opts.json) {
-      outputJson({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report });
+      outputJson({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report, savedTo });
       return;
     }
     printReport(report, corpus.workspaces.length, withSessions);
+    if (savedTo) logInfo(`Saved report to ${colorize(savedTo, 'dim')}`);
   } catch (error) {
     const msg = error instanceof Error ? error.message : 'reflect failed';
     if (opts.json) outputJsonError(msg);

package/src/utils/reflect.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from 'vitest';
-import { distillTranscript, parseReflectionReport, classifyAgentsMd, isCorrectionPrompt } from './reflect';
+import { distillTranscript, parseReflectionReport, classifyAgentsMd, isCorrectionPrompt, saveReflectionReport } from './reflect';
+import * as fs from 'fs/promises';
+import * as path from 'path';
 
 const J = (o: unknown) => JSON.stringify(o);
 
@@ -53,6 +55,24 @@ describe('distillTranscript', () => {
   });
 });
 
+describe('saveReflectionReport', () => {
+  it('writes a timestamped JSON report (sanitized scope) and returns its path', async () => {
+    const file = await saveReflectionReport(
+      { summary: 'ok', recommendations: [{ kind: 'skill', title: 't', detail: 'd', priority: 'high' }] },
+      { analyzed: 2, workspaces: 3, workspace: 'pay/app' },
+    );
+    try {
+      expect(file).toMatch(/\.json$/);
+      expect(path.basename(file)).toContain('pay_app'); // scope suffix, path-sanitized
+      const written = JSON.parse(await fs.readFile(file, 'utf-8'));
+      expect(written).toMatchObject({ analyzed: 2, workspaces: 3, workspace: 'pay/app', summary: 'ok' });
+      expect(written.generatedAt).toBeTruthy();
+    } finally {
+      await fs.rm(file, { force: true });
+    }
+  });
+});
+
 describe('classifyAgentsMd', () => {
   it('distinguishes missing / boilerplate / substantive', () => {
     expect(classifyAgentsMd('')).toBe('missing');

package/src/utils/reflect.ts

@@ -1,5 +1,6 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
+import { CACHE_DIR } from './config';
 import { listWorkspaces } from './workspace-meta';
 import { getAgentPaths, getSkillsTargetDirs, getAllKnownContextFileNames, ConcreteAgentType } from './agent-config';
 import { pathToProjectDirName, getWorkspaceSessions, WorkspaceSession } from './claude-sessions';
@@ -344,6 +345,7 @@ export interface ReflectProgress {
 export async function gatherReflectionCorpus(
   limit: number,
   onProgress?: (p: ReflectProgress) => void,
+  opts: { workspace?: string } = {},
 ): Promise<ReflectionCorpus> {
   const [sessions, workspaces, availableSkills] = await Promise.all([
     getWorkspaceSessions(), // already sorted by last-active, one per workspace
@@ -351,7 +353,10 @@ export async function gatherReflectionCorpus(
     listAvailableSkills(),
   ]);
   const metaByName = new Map(workspaces.map((w) => [w.name, w]));
-  const recent = sessions.slice(0, limit);
+  // A single named workspace (ignores limit), else the N most recently active.
+  const recent = opts.workspace
+    ? sessions.filter((s) => s.workspaceName === opts.workspace)
+    : sessions.slice(0, limit);
 
   const digests: WorkspaceDigest[] = [];
   for (let index = 0; index < recent.length; index++) {
@@ -428,3 +433,25 @@ export function parseReflectionReport(parsed: unknown): ReflectionReport {
     .filter((r: Recommendation | null): r is Recommendation => r !== null);
   return { summary, recommendations };
 }
+
+// -------------------------------------------------------------- report saving
+
+/** Where saved reflection reports live: `~/.nemus/reflect/`. */
+export const REFLECT_REPORTS_DIR = path.join(CACHE_DIR, 'reflect');
+
+/**
+ * Persist a reflection report as timestamped JSON under `~/.nemus/reflect/`, so
+ * a run can be revisited or diffed over time. Returns the written path. Pure
+ * side-effect (mkdir -p + write); callers treat failure as non-fatal.
+ */
+export async function saveReflectionReport(
+  report: ReflectionReport,
+  meta: { analyzed: number; workspaces: number; workspace?: string },
+): Promise<string> {
+  await fs.mkdir(REFLECT_REPORTS_DIR, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const scope = meta.workspace ? `-${meta.workspace.replace(/[^a-zA-Z0-9_-]+/g, '_')}` : '';
+  const file = path.join(REFLECT_REPORTS_DIR, `${stamp}${scope}.json`);
+  await fs.writeFile(file, JSON.stringify({ generatedAt: new Date().toISOString(), ...meta, ...report }, null, 2));
+  return file;
+}