@mmnto/cli 1.94.0 → 1.96.0

package/dist/help.js

@@ -1,5 +1,5 @@
 import { Help } from 'commander';
-/** Commands that require an LLM orchestrator */
+/** Commands that require an LLM orchestrator (rendered with an [LLM] badge). */
 export const LLM_COMMANDS = new Set([
     'review',
     'spec',
@@ -10,83 +10,112 @@ export const LLM_COMMANDS = new Set([
     'triage',
     'triage-pr',
 ]);
-/** Command grouping for root help */
-export const COMMAND_GROUPS = [
-    {
-        name: 'Core',
-        commands: ['lint', 'review', 'check', 'spec'],
-    },
-    {
-        name: 'Entities',
-        commands: ['rule', 'lesson', 'exemption', 'config'],
-    },
-    {
-        name: 'Workflow',
-        commands: ['wrap', 'triage', 'triage-pr', 'review-learn'],
-    },
-    {
-        name: 'Setup',
-        commands: ['init', 'sync', 'hooks', 'doctor', 'status', 'orient', 'eject'],
-    },
+/**
+ * The ONE declared consumer tier (mmnto-ai/totem#2336 D2, panel-ruled; ADR-094
+ * "operator memory cliff"). Default `totem --help` renders EXACTLY these entries
+ * plus a pointer to the full surface; every other command is the advanced tier,
+ * enumerable via `totem help --all`. This single exported surface is the source
+ * of truth — tiering must NEVER be scattered as per-command flags (a per-command
+ * flag re-opens the drift this consolidates). Entries may be subcommand paths
+ * ('lesson add'); the renderer resolves them against the LIVE command tree so
+ * their descriptions never drift from the registration.
+ *
+ * `status` is a panel addition — the first-hour health check.
+ *
+ * Hiding is an information surface, never a gate (Tenet 12/13): every advanced
+ * command stays 100% functional and is one `totem help --all` away.
+ */
+export const CONSUMER_TIER = [
+    'init',
+    'lint',
+    'lesson add',
+    'lesson compile',
+    'doctor',
+    'search',
+    'status',
 ];
+/**
+ * Render-time freeze badge (mmnto-ai/totem#2336 D2.4). Prefixes the frozen
+ * command's help line. Derived from the freeze primitive by the caller
+ * (see help-freeze.ts) and passed in as a boolean — NEVER hardcoded here
+ * (Tenet 20): the freeze is a cohort fact, not a product fact, so a consumer
+ * with no freeze.json/doctrine pin renders the plain line.
+ */
+const FROZEN_BADGE = '[frozen] ';
+/** The command whose help line the rule-compilation freeze decorates. */
+const FREEZE_BADGED_COMMAND = 'lesson compile';
+const COLUMN_PADDING = 2;
 export class TotemHelp extends Help {
+    totemOpts;
+    constructor(totemOpts = {}) {
+        super();
+        this.totemOpts = totemOpts;
+    }
     formatHelp(cmd, helper) {
-        // Only override root command help
+        // Only override ROOT help; subcommand help uses Commander's default.
         if (cmd.parent) {
             return super.formatHelp(cmd, helper);
         }
-        const visible = helper
-            .visibleCommands(cmd)
-            .filter((c) => c.name() !== 'help')
-            .map((c) => ({
-            name: c.name(),
-            description: helper.subcommandDescription(c),
-        }));
-        const visibleByName = new Map(visible.map((c) => [c.name, c]));
-        const usedNames = new Set();
+        const all = this.totemOpts.all === true;
+        const freezeActive = this.totemOpts.freezeActive === true;
         const cliName = cmd.name();
         const cliDescription = cmd.description() || 'Totem';
+        // Resolve a declared tier entry (possibly a subcommand path like
+        // 'lesson add') to its live description. Unresolvable entries are skipped
+        // so a partial program (e.g. a test harness) degrades gracefully.
+        const resolve = (entryPath) => {
+            const parts = entryPath.split(' ');
+            let current = cmd;
+            for (const part of parts) {
+                current = current?.commands.find((c) => c.name() === part);
+                if (current === undefined)
+                    return undefined;
+            }
+            const base = current.description();
+            const description = freezeActive && entryPath === FREEZE_BADGED_COMMAND ? FROZEN_BADGE + base : base;
+            return { name: entryPath, description };
+        };
+        const consumerEntries = CONSUMER_TIER.map(resolve).filter((e) => e !== undefined);
         let output = `${cliDescription}\n\n`;
         output += `Usage: ${cliName} [command]\n\n`;
-        const COLUMN_PADDING = 2;
-        // Render each group
-        for (const group of COMMAND_GROUPS) {
-            const groupCmds = group.commands
-                .filter((name) => visibleByName.has(name))
-                .map((name) => {
-                usedNames.add(name);
-                const entry = visibleByName.get(name);
-                const badge = LLM_COMMANDS.has(name) ? ' [LLM]' : '';
-                return { displayName: name + badge, description: entry.description };
-            });
-            if (groupCmds.length === 0)
-                continue;
-            output += `${group.name}:\n`;
-            const pad = Math.max(...groupCmds.map((c) => c.displayName.length)) + COLUMN_PADDING;
-            for (const c of groupCmds) {
-                output += `  ${c.displayName.padEnd(pad)}${c.description}\n`;
-            }
-            output += '\n';
-        }
-        // Fallback: any commands not in a group
-        const ungrouped = visible.filter((c) => !usedNames.has(c.name));
-        if (ungrouped.length > 0) {
-            output += `Other:\n`;
-            const allNames = ungrouped.map((c) => {
-                const badge = LLM_COMMANDS.has(c.name) ? ' [LLM]' : '';
-                return c.name + badge;
-            });
-            const pad = Math.max(...allNames.map((n) => n.length)) + COLUMN_PADDING;
-            for (let i = 0; i < ungrouped.length; i++) {
-                const c = ungrouped[i];
-                const displayName = allNames[i];
-                output += `  ${displayName.padEnd(pad)}${c.description}\n`;
-            }
-            output += '\n';
+        if (!all) {
+            output += this.renderSection('Commands:', consumerEntries);
+            output += `Run '${cliName} help --all' for the full command surface.\n`;
+            output += `Run '${cliName} <command> --help' for details on a specific command.\n`;
+            output += `Version: ${cmd.version()}\n`;
+            return output;
         }
+        // --all: consumer tier + everything else (advanced), tiered. Advanced is
+        // derived from the LIVE command tree (visibleCommands respects `hidden`),
+        // so it can never drift from the registration. A top-level command whose
+        // full name is itself a consumer entry (init/lint/doctor/search/status) is
+        // omitted from advanced; a noun like `lesson` STAYS in advanced so its
+        // other verbs remain discoverable even though `lesson add`/`lesson compile`
+        // are promoted to the consumer tier.
+        output += this.renderSection('Consumer commands:', consumerEntries);
+        const consumerTopLevel = new Set(CONSUMER_TIER.filter((p) => !p.includes(' ')));
+        const advancedEntries = helper
+            .visibleCommands(cmd)
+            .filter((c) => c.name() !== 'help' && !consumerTopLevel.has(c.name()))
+            .map((c) => ({
+            name: LLM_COMMANDS.has(c.name()) ? `${c.name()} [LLM]` : c.name(),
+            description: c.description(),
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        output += this.renderSection('Advanced commands:', advancedEntries);
         output += `Run '${cliName} <command> --help' for details on a specific command.\n`;
         output += `Version: ${cmd.version()}\n`;
         return output;
     }
+    renderSection(title, entries) {
+        if (entries.length === 0)
+            return '';
+        const pad = Math.max(...entries.map((e) => e.name.length)) + COLUMN_PADDING;
+        let s = `${title}\n`;
+        for (const e of entries) {
+            s += `  ${e.name.padEnd(pad)}${e.description}\n`;
+        }
+        return s + '\n';
+    }
 }
 //# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}

package/dist/help.test.js

@@ -1,95 +1,119 @@
 import { Command } from 'commander';
 import { describe, expect, it } from 'vitest';
-import { COMMAND_GROUPS, LLM_COMMANDS, TotemHelp } from './help.js';
-describe('TotemHelp', () => {
+import { CONSUMER_TIER, LLM_COMMANDS, TotemHelp } from './help.js';
+describe('TotemHelp (tiered — mmnto-ai/totem#2336 D2)', () => {
     function createMockProgram() {
         const program = new Command('totem');
         program.version('1.0.0');
-        program.configureHelp(new TotemHelp());
+        program.description('Totem — test description');
+        // Consumer tier (top-level)
+        program.command('init').description('Initialize Totem');
         program.command('lint').description('Run compiled rules');
+        program.command('doctor').description('Run workspace health diagnostics');
+        program.command('search <query>').description('Search the knowledge index');
+        program.command('status').description('Show current project health');
+        // Consumer tier entries that are subcommand paths under `lesson`
+        const lesson = program.command('lesson').description('Manage project lessons');
+        lesson.command('add <text>').description('Add a lesson to project memory');
+        lesson.command('compile').description('Compile lesson files into deterministic lint rules');
+        lesson.command('list').description('List all lessons');
+        // Advanced-only commands (must NOT appear in default help)
+        program.command('mail').description('Show unread cross-repo mail');
+        program.command('orient').description('Derive session orientation');
+        program.command('handoff').description('Scaffold a journal entry for handoff');
         program.command('review').description('AI-powered code review');
-        program.command('rule').description('Manage compiled rules');
-        program.command('init').description('Initialize Totem');
-        program.command('unknown-cmd').description('Some new command');
         return program;
     }
-    it('groups commands under defined categories', () => {
+    it('default help renders exactly the consumer tier plus the pointer', () => {
         const program = createMockProgram();
         const help = new TotemHelp();
         const output = help.formatHelp(program, help);
-        expect(output).toContain('Core:');
-        expect(output).toContain('Entities:');
-        expect(output).toContain('Setup:');
+        expect(output.startsWith('Totem — test description')).toBe(true);
+        expect(output).toContain('Commands:');
+        for (const entry of CONSUMER_TIER) {
+            expect(output).toContain(entry);
+        }
+        expect(output).toContain("Run 'totem help --all' for the full command surface.");
+        // Advanced commands are hidden from the default surface
+        expect(output).not.toContain('mail');
+        expect(output).not.toContain('orient');
+        // No --all section headers in the default view
+        expect(output).not.toContain('Advanced commands:');
     });
-    it('adds [LLM] badge to LLM-dependent commands', () => {
+    it('--all lists both tiers and includes advanced + continuity commands', () => {
         const program = createMockProgram();
-        const help = new TotemHelp();
+        const help = new TotemHelp({ all: true });
         const output = help.formatHelp(program, help);
-        expect(output).toContain('review [LLM]');
-        expect(output).not.toContain('lint [LLM]');
+        expect(output).toContain('Consumer commands:');
+        expect(output).toContain('Advanced commands:');
+        // Known advanced command surfaces under --all
+        expect(output).toContain('mail');
+        expect(output).toContain('orient');
+        // Continuity primitives (D5 caveat) stay visibly present in advanced
+        expect(output).toContain('handoff');
+        // Consumer entries still render
+        expect(output).toContain('lesson compile');
+        // The `lesson` NOUN stays discoverable in advanced even though two of its
+        // verbs are promoted to the consumer tier
+        expect(output).toMatch(/Advanced commands:[\s\S]*\blesson\b/);
     });
-    it('puts uncategorized commands in Other group', () => {
+    it('badges LLM commands in the advanced tier', () => {
         const program = createMockProgram();
-        const help = new TotemHelp();
+        const help = new TotemHelp({ all: true });
         const output = help.formatHelp(program, help);
-        expect(output).toContain('Other:');
-        expect(output).toContain('unknown-cmd');
+        expect(output).toContain('review [LLM]');
     });
-    it('uses default help for subcommands', () => {
+    it('prefixes the lesson compile line with [frozen] only when a freeze is active', () => {
         const program = createMockProgram();
-        const rule = program.commands.find((c) => c.name() === 'rule');
-        rule.command('list').description('List all rules');
-        const help = new TotemHelp();
-        const output = help.formatHelp(rule, help);
-        // Subcommand help should use Commander default — contains 'list'
-        expect(output).toContain('list');
-        // Should NOT contain our custom group headers
-        expect(output).not.toContain('Core:');
+        const frozen = new TotemHelp({ freezeActive: true });
+        const frozenOut = frozen.formatHelp(program, frozen);
+        expect(frozenOut).toContain('[frozen] Compile lesson files into deterministic lint rules');
+        const plain = new TotemHelp({ freezeActive: false });
+        const plainOut = plain.formatHelp(program, plain);
+        expect(plainOut).not.toContain('[frozen]');
     });
-    it('does not show help command in Other group', () => {
+    it('the freeze badge is present under --all too', () => {
         const program = createMockProgram();
-        const help = new TotemHelp();
+        const help = new TotemHelp({ all: true, freezeActive: true });
         const output = help.formatHelp(program, help);
-        // 'help' is a built-in Commander command — should be excluded from Other
-        // Extract the Other section lines (between "Other:" and the next blank line)
-        const otherMatch = output.match(/Other:\n([\s\S]*?)\n\n/);
-        if (otherMatch) {
-            expect(otherMatch[1]).not.toMatch(/^\s+help\b/m);
-        }
+        expect(output).toContain('[frozen] Compile lesson files into deterministic lint rules');
     });
-    it('skips empty groups', () => {
-        const program = new Command('totem');
-        program.version('1.0.0');
-        program.configureHelp(new TotemHelp());
-        program.command('lint').description('Run compiled rules');
-        // Only lint exists — Workflow group should not appear
+    it('uses default Commander help for subcommands', () => {
+        const program = createMockProgram();
+        const lesson = program.commands.find((c) => c.name() === 'lesson');
         const help = new TotemHelp();
-        const output = help.formatHelp(program, help);
-        expect(output).toContain('Core:');
-        expect(output).not.toContain('Workflow:');
+        const output = help.formatHelp(lesson, help);
+        // Subcommand help lists the noun's subcommands and does NOT use the tiered
+        // root render.
+        expect(output).toContain('add');
+        expect(output).not.toContain('Consumer commands:');
     });
     it('includes version in output', () => {
         const program = createMockProgram();
         const help = new TotemHelp();
-        const output = help.formatHelp(program, help);
-        expect(output).toContain('Version: 1.0.0');
+        expect(help.formatHelp(program, help)).toContain('Version: 1.0.0');
     });
-    it('does not show hidden commands', () => {
+    it('does not surface hidden commands under --all', () => {
         const program = createMockProgram();
         program.command('secret-cmd', { hidden: true }).description('Should not appear');
-        const help = new TotemHelp();
-        const output = help.formatHelp(program, help);
-        expect(output).not.toContain('secret-cmd');
+        const help = new TotemHelp({ all: true });
+        expect(help.formatHelp(program, help)).not.toContain('secret-cmd');
     });
-    it('COMMAND_GROUPS covers expected categories', () => {
-        const groupNames = COMMAND_GROUPS.map((g) => g.name);
-        expect(groupNames).toEqual(['Core', 'Entities', 'Workflow', 'Setup']);
+    it('CONSUMER_TIER is the declared consumer surface (order-stable)', () => {
+        expect([...CONSUMER_TIER]).toEqual([
+            'init',
+            'lint',
+            'lesson add',
+            'lesson compile',
+            'doctor',
+            'search',
+            'status',
+        ]);
     });
     it('LLM_COMMANDS contains expected entries', () => {
         expect(LLM_COMMANDS.has('review')).toBe(true);
         expect(LLM_COMMANDS.has('lint')).toBe(false);
         expect(LLM_COMMANDS.has('spec')).toBe(true);
-        expect(LLM_COMMANDS.has('wrap')).toBe(true);
     });
 });
 //# sourceMappingURL=help.test.js.map

package/dist/help.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.test.js","sourceRoot":"","sources":["../src/help.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"help.test.js","sourceRoot":"","sources":["../src/help.test.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { z } from 'zod';
 import { initCommand } from './commands/init.js';
+import { TOTEM_DESCRIPTION } from './description.js';
 import { REVIEW_DIFF_TRUNCATION_THRESHOLD } from './git.js';
 import { TotemHelp } from './help.js';
 import { reapOrphanedTempFiles } from './utils.js';
@@ -72,13 +73,22 @@ function handleError(err) {
     process.exit(1);
 }
 const program = new Command();
+// Root-help tier state (mmnto-ai/totem#2336 D2). Mutated before help renders
+// (the `--help` option path precomputes below; the `help` command action sets
+// it directly) and read back by the configured formatHelp via this closure —
+// the bridge between commander's SYNCHRONOUS help render and the ASYNC freeze
+// read that derives the `[frozen]` badge.
+const helpState = { all: false, freezeActive: false };
 program
     .name('totem')
-    .description('Totem — persistent memory and context layer for AI agents')
+    .description(TOTEM_DESCRIPTION)
     .version(version)
     .option('--json', 'Output structured JSON to stdout')
+    // Disable commander's built-in help command so our tiered `help [command...]
+    // --all` command (registered below) owns `totem help`.
+    .helpCommand(false)
     .configureHelp({
-    formatHelp: (cmd, helper) => new TotemHelp().formatHelp(cmd, helper),
+    formatHelp: (cmd, helper) => new TotemHelp({ all: helpState.all, freezeActive: helpState.freezeActive }).formatHelp(cmd, helper),
 });
 // Set JSON mode early — preAction may not fire on parse errors
 if (process.argv.includes('--json')) {
@@ -1200,7 +1210,7 @@ lessonCmd
 });
 lessonCmd
     .command('compile')
-    .description('Compile lessons into deterministic regex rules')
+    .description('Compile lesson files into deterministic lint rules')
     .option('--raw', 'Output compiler prompts without LLM synthesis')
     .option('--out <path>', 'Write output to a file instead of stdout')
     .option('--model <name>', 'Override the default model for the orchestrator')
@@ -1625,6 +1635,72 @@ windtunnelCmd
         throw err;
     }
 });
+// Derive the `[frozen]` badge state for root help (mmnto-ai/totem#2336 D2.4)
+// from the canonical freeze primitive. Only ever called on a help render, so
+// ordinary commands never pay for the freeze read.
+async function computeFreezeActive() {
+    const { deriveRuleCompilationFrozen } = await import('./help-freeze.js');
+    return deriveRuleCompilationFrozen(process.cwd());
+}
+// Tiered help surface (mmnto-ai/totem#2336 D2). Replaces commander's built-in
+// help command (disabled via .helpCommand(false)) so `totem help --all` renders
+// the FULL command surface, tiered, while `totem help <command>` still delegates
+// to the default per-command help. Bare `totem help` / `totem --help` show only
+// the consumer tier plus the pointer to `--all` (partially addresses the
+// progressive-disclosure ask in mmnto-ai/totem#1722; grouping is left to it).
+program
+    .command('help [command...]')
+    .description('Show help; add --all for the full command surface (consumer + advanced tiers)')
+    .option('--all', 'List every command, grouped into consumer and advanced tiers')
+    .action(async (commandPath, opts) => {
+    try {
+        if (commandPath.length > 0) {
+            let target = program;
+            for (const part of commandPath) {
+                target = target?.commands.find((c) => c.name() === part);
+            }
+            if (target !== undefined && target !== program) {
+                target.outputHelp();
+                return;
+            }
+            const { TotemConfigError } = await import('@mmnto/totem');
+            throw new TotemConfigError(`Unknown command: ${commandPath.join(' ')}`, "Run 'totem help --all' to list every command.", 'CONFIG_INVALID');
+        }
+        helpState.all = opts.all === true;
+        helpState.freezeActive = await computeFreezeActive();
+        program.outputHelp();
+    }
+    catch (err) {
+        handleError(err);
+        // handleError returns `never` (process.exit); the throw is unreachable but
+        // required to satisfy the Tenet 4 fail-loud rule that bans bare-catch
+        // silent-degrade. Mirrors the stats/mail command pattern in this file.
+        throw err;
+    }
+});
+// Precompute root-help tier state for the `--help`/`-h` OPTION path (the `help`
+// COMMAND path sets it in its own action above). `--all` is cheap to read
+// always. The freeze read fires ONLY for ROOT help (`totem --help`), never for
+// subcommand help (`totem lint --help`) — the badge renders only on the root
+// surface, and gating on isRootHelpInvocation keeps a corrupt freeze.json from
+// breaking unrelated `totem <command> --help`. A corrupt freeze on the root
+// path still surfaces loudly via handleError (no fail-open).
+helpState.all = process.argv.includes('--all');
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    const { isRootHelpInvocation } = await import('./help-freeze.js');
+    if (isRootHelpInvocation(process.argv.slice(2))) {
+        try {
+            helpState.freezeActive = await computeFreezeActive();
+        }
+        catch (err) {
+            handleError(err);
+            // handleError returns `never` (process.exit); the throw is unreachable
+            // but required to satisfy the Tenet 4 fail-loud rule that bans bare-catch
+            // silent-degrade. Mirrors the stats/mail command pattern in this file.
+            throw err;
+        }
+    }
+}
 // Fire-and-forget: reap orphaned temp files from previous crashed runs
 reapOrphanedTempFiles(process.cwd(), '.totem').catch(() => { });
 try {