@hanzlaa/rcode 2.1.0

package/cli/lib/prompts.cjs

@@ -0,0 +1,355 @@
+/**
+ * Zero-dep interactive prompt helpers for the Rihal Code CLI.
+ *
+ * Why this exists:
+ *   Hand-rolled readline.question() crashes or silently aborts when a user
+ *   types an unexpected value (e.g. "a" instead of "1"). (prior tooling used)
+ *   @clack/prompts; we stay zero-dep by implementing a small, well-tested
+ *   helper with validation loops, friendly errors, and clean SIGINT/EOF
+ *   handling.
+ *
+ * Public API:
+ *   askChoice(question, { choices, default, allowMulti, expand, maxAttempts })
+ *     → Promise<string[]>   (resolved ids)
+ *   askConfirm(question, { default, maxAttempts })
+ *     → Promise<boolean>
+ *   askText(question, { default, validate, maxAttempts })
+ *     → Promise<string>
+ *   PromptAbortError          — thrown on EOF / max-attempts / explicit abort
+ *
+ * All helpers:
+ *   - Create and close their own readline.Interface (no leaks).
+ *   - Install a one-shot SIGINT handler on first use that prints "Cancelled."
+ *     and exits 0 (no stack trace).
+ *   - Re-prompt on invalid input up to maxAttempts (default 3) rounds.
+ *   - Accept empty input as "use default" when a default is provided.
+ */
+
+const readline = require('readline');
+
+class PromptAbortError extends Error {
+  constructor(message = 'Prompt aborted') {
+    super(message);
+    this.name = 'PromptAbortError';
+  }
+}
+
+// Install SIGINT handler once — repeated requires don't stack handlers.
+let sigintInstalled = false;
+function installSigintHandler() {
+  if (sigintInstalled) return;
+  sigintInstalled = true;
+  process.on('SIGINT', () => {
+    // Newline so the "Cancelled." line doesn't append to the half-typed prompt.
+    process.stdout.write('\n\nCancelled.\n');
+    process.exit(0);
+  });
+}
+
+/**
+ * Process-wide shared readline session.
+ *
+ * Why singleton: opening and closing a fresh readline.Interface for each
+ * prompt loses buffered pipe input between prompts — the second session
+ * sees stdin as already closed (EOF). So we keep exactly one session for
+ * the whole process lifetime. It's cheap (one interface) and it exits
+ * naturally when the process exits.
+ *
+ * Why line-event queue instead of rl.question(): node's rl.question() has
+ * a known quirk where the second call on piped input hangs even with
+ * more lines buffered. A line queue + pending-resolver pattern avoids it.
+ */
+let sharedSession = null;
+function getSession() {
+  if (sharedSession) return sharedSession;
+  sharedSession = openSession();
+  return sharedSession;
+}
+
+function openSession() {
+  installSigintHandler();
+  const isTTY = !!process.stdin.isTTY;
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: isTTY,
+  });
+
+  let closedByUs = false;
+  let streamClosed = false;
+
+  rl.on('close', () => {
+    streamClosed = true;
+  });
+
+  // Two code paths:
+  //
+  // 1. TTY mode — hand the whole ask off to rl.question(). Readline
+  //    owns printing the prompt, tracking cursor position, handling
+  //    backspace / arrow keys / history. If we printed the prompt
+  //    ourselves, readline's internal cursor tracking walks past the
+  //    prompt on backspace and erases it — that was the bug in #16.
+  //
+  // 2. Piped mode (CI, test harness, rihal-code install | tee ...) —
+  //    rl.question() has a quirk where the second call in a sequence
+  //    can miss the next buffered line. The line-event queue pattern
+  //    below avoids it: we listen for `line` events ourselves and
+  //    match them to pending waiters.
+  //
+  // Both paths share the same closed-stream handling and abort semantics.
+
+  const lineQueue = [];
+  const waiters = [];
+
+  if (!isTTY) {
+    rl.on('line', (line) => {
+      if (waiters.length > 0) {
+        const { resolve } = waiters.shift();
+        resolve(line);
+      } else {
+        lineQueue.push(line);
+      }
+    });
+    rl.on('close', () => {
+      // Reject every pending waiter so askers don't hang forever.
+      while (waiters.length > 0) {
+        const { reject } = waiters.shift();
+        if (!closedByUs) {
+          reject(new PromptAbortError('Input stream closed'));
+        }
+      }
+    });
+  }
+
+  function ask(question) {
+    if (isTTY) {
+      if (streamClosed) {
+        return Promise.reject(new PromptAbortError('Input stream closed'));
+      }
+      // Readline handles the whole prompt lifecycle: print, cursor,
+      // backspace, submit. No manual process.stdout.write here — that
+      // was the source of the backspace-erases-prompt bug (#16).
+      return new Promise((resolve, reject) => {
+        // readline docs: on close while a question is pending, resolve
+        // is invoked with undefined. We treat that as abort.
+        let settled = false;
+        const onClose = () => {
+          if (!settled && !closedByUs) {
+            settled = true;
+            reject(new PromptAbortError('Input stream closed'));
+          }
+        };
+        rl.once('close', onClose);
+        rl.question(question, (answer) => {
+          if (settled) return;
+          settled = true;
+          rl.removeListener('close', onClose);
+          resolve((answer || '').trim());
+        });
+      });
+    }
+
+    // Piped path — print prompt manually, drain queue before giving up.
+    process.stdout.write(question);
+
+    // CRITICAL: check the queue FIRST, even if the stream has closed.
+    // Lines that were already read but not yet consumed must still be
+    // returned. Only reject when both the queue is empty AND the stream
+    // is closed — nothing more is coming.
+    if (lineQueue.length > 0) {
+      return Promise.resolve((lineQueue.shift() || '').trim());
+    }
+    if (streamClosed) {
+      return Promise.reject(new PromptAbortError('Input stream closed'));
+    }
+    return new Promise((resolve, reject) => {
+      waiters.push({
+        resolve: (line) => resolve((line || '').trim()),
+        reject,
+      });
+    });
+  }
+
+  function close() {
+    closedByUs = true;
+    rl.close();
+  }
+
+  return { ask, close };
+}
+
+/**
+ * Ask the user to pick one or more choices from a list.
+ *
+ * choices: array of { key, id, label }
+ *   - `key` is the short token the user types ("1", "2", ...).
+ *   - `id`  is the canonical identifier returned to the caller.
+ *   - `label` is the human name shown in error messages.
+ *
+ * Options:
+ *   default      — default token(s) when user hits Enter (string, may be comma list)
+ *   allowMulti   — if false, reject multi-token answers (default: true)
+ *   expand       — optional (id) => string[] to expand aliases like "all"
+ *   maxAttempts  — retry limit on all-invalid input (default: 3)
+ *
+ * Return value semantics:
+ *   - All tokens valid  → return resolved/expanded ids
+ *   - Mixed valid+invalid → accept valid, warn about invalid, return (no re-prompt)
+ *   - Zero valid tokens  → print friendly error + list valid options + re-prompt
+ *   - After maxAttempts failed rounds → throw PromptAbortError
+ */
+async function askChoice(
+  question,
+  {
+    choices,
+    default: defaultAnswer = '',
+    allowMulti = true,
+    expand = null,
+    maxAttempts = 3,
+  } = {}
+) {
+  if (!Array.isArray(choices) || choices.length === 0) {
+    throw new Error('askChoice: `choices` must be a non-empty array');
+  }
+
+  const validKeys = choices.map((c) => c.key);
+  const validIds = choices.map((c) => c.id);
+  const hint = `Valid options: ${validKeys.join(', ')} (or ${validIds.join(', ')})`;
+
+  const session = getSession();
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const raw = await session.ask(question);
+    const source = raw === '' ? defaultAnswer : raw;
+
+    if (source === '') {
+      console.log(`   ⚠ No input and no default. ${hint}`);
+      continue;
+    }
+
+    const tokens = source
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    if (!allowMulti && tokens.length > 1) {
+      console.log(`   ⚠ Only one choice allowed, you typed ${tokens.length}.`);
+      continue;
+    }
+
+    const resolved = [];
+    const invalid = [];
+    for (const tok of tokens) {
+      const match = choices.find((c) => c.key === tok || c.id === tok);
+      if (!match) {
+        invalid.push(tok);
+      } else if (expand) {
+        for (const id of expand(match.id)) resolved.push(id);
+      } else {
+        resolved.push(match.id);
+      }
+    }
+
+    if (resolved.length === 0) {
+      console.log(`   ⚠ Didn't recognize: ${invalid.map((t) => `"${t}"`).join(', ')}`);
+      console.log(`   ${hint}`);
+      console.log();
+      continue;
+    }
+
+    if (invalid.length > 0) {
+      console.log(`   ⚠ Skipping unknown: ${invalid.map((t) => `"${t}"`).join(', ')}`);
+    }
+
+    // Deduplicate while preserving order
+    return [...new Set(resolved)];
+  }
+
+  throw new PromptAbortError(
+    `No valid selection after ${maxAttempts} attempts`
+  );
+}
+
+/**
+ * Yes/no prompt. Returns boolean.
+ *
+ * Options:
+ *   default       — 'y' | 'n' (default: 'n')
+ *   maxAttempts   — retry limit (default: 3)
+ */
+async function askConfirm(
+  question,
+  { default: defaultAnswer = 'n', maxAttempts = 3 } = {}
+) {
+  const dflt = defaultAnswer.toLowerCase() === 'y' ? 'y' : 'n';
+
+  const session = getSession();
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const raw = (await session.ask(question)).toLowerCase();
+    const answer = raw === '' ? dflt : raw;
+
+    if (answer === 'y' || answer === 'yes') return true;
+    if (answer === 'n' || answer === 'no') return false;
+
+    console.log(`   ⚠ Please answer "y" or "n".`);
+  }
+
+  throw new PromptAbortError(
+    `No valid yes/no answer after ${maxAttempts} attempts`
+  );
+}
+
+/**
+ * Free-text prompt with optional validation.
+ *
+ * Options:
+ *   default      — returned when user hits Enter with no input
+ *   validate     — (value) => true | string  (string = error message to show)
+ *   maxAttempts  — retry limit (default: 3)
+ */
+async function askText(
+  question,
+  { default: defaultAnswer = '', validate = null, maxAttempts = 3 } = {}
+) {
+  const session = getSession();
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const raw = await session.ask(question);
+    const value = raw === '' ? defaultAnswer : raw;
+
+    if (validate) {
+      const result = validate(value);
+      if (result !== true) {
+        console.log(`   ⚠ ${typeof result === 'string' ? result : 'Invalid input.'}`);
+        continue;
+      }
+    } else if (value === '') {
+      console.log(`   ⚠ Please enter a value.`);
+      continue;
+    }
+
+    return value;
+  }
+
+  throw new PromptAbortError(
+    `No valid text input after ${maxAttempts} attempts`
+  );
+}
+
+/**
+ * Close the shared session so the process can exit cleanly.
+ * Safe to call even if no prompts were used. Idempotent.
+ */
+function closeSession() {
+  if (sharedSession) {
+    sharedSession.close();
+    sharedSession = null;
+  }
+}
+
+module.exports = {
+  askChoice,
+  askConfirm,
+  askText,
+  closeSession,
+  PromptAbortError,
+};

package/cli/postinstall.js

@@ -0,0 +1,32 @@
+/**
+ * rihal-code postinstall hook — runs automatically after `npm install`
+ */
+
+// Only print the welcome if not running in CI/test environments
+if (process.env.CI || process.env.NODE_ENV === 'test') {
+  process.exit(0);
+}
+
+console.log(`
+🕌 Rihal Code installed.
+
+First-time setup:
+  npx @hanzlahabib/rihal-code install     # set up agents + slash commands
+  npx @hanzlahabib/rihal-code tiers       # see the tier map
+
+🌱 The Golden Path (say these phrases in your AI IDE):
+  1. "scaffold a new project"     → rihal-scaffold-project
+  2. "create a PRD"               → rihal-create-prd
+  3. "create a story"             → rihal-create-story
+  4. "plan a sprint"              → rihal-sprint-planning
+  5. "dev this story"             → rihal-dev-story
+  6. "review this code"           → rihal-code-review
+  7. "sprint status"              → rihal-sprint-status
+
+More:
+  npx @hanzlahabib/rihal-code help        # all commands (grouped)
+  npx @hanzlahabib/rihal-code dashboard   # view-only Diwan on :7717
+
+Docs: https://github.com/hanzlahabib/rihal-code
+Tiers: docs/TIERS.md   ·   Standards: docs/STANDARDS.md
+`);

package/cli/set-mode.js

@@ -0,0 +1,94 @@
+/**
+ * rihal-code set-mode — toggle the communication mode.
+ *
+ * Thin wrapper over `rihal-code config communication_mode <value>` with
+ * inline explanations of what each mode changes. Supports the same
+ * typo suggestions as the underlying config setter.
+ *
+ * Usage:
+ *   rihal-code set-mode                show current mode + explanation
+ *   rihal-code set-mode guided         switch to guided (ask at gates)
+ *   rihal-code set-mode yolo           switch to yolo (skip menus, trust defaults)
+ *
+ * Affects:
+ *   - Workflow step files ("halt at menu" vs "pick default and continue")
+ *   - /rihal:kickoff next-step menu (interactive vs auto-continue)
+ *   - github-sync confirmation prompts (yolo still requires --force-yolo
+ *     for github mutations — see docs/adr/0001-github-sync-as-cli.md)
+ *   - /rihal:pause and /rihal:resume (yolo skips the confirmation prompt
+ *     on resume; guided always asks)
+ *   - All agent skill files that read communication_mode from config
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  loadConfig,
+  setConfigValue,
+  VALID_COMMUNICATION_MODES,
+} = require('./lib/config.cjs');
+
+const MODE_DESCRIPTIONS = {
+  guided:
+    'Ask questions, confirm at every major gate, halt at decision menus.\n' +
+    '     Recommended for: first-time use, critical projects, new domains.',
+  yolo:
+    'Skip menus, use sensible defaults, report decisions in the final summary.\n' +
+    '     Destructive ops (github push, rm, force-push) STILL require\n' +
+    '     explicit confirmation unless you also pass --force-yolo.\n' +
+    '     Recommended for: experienced solo projects, prototypes, CI.',
+};
+
+module.exports = function setMode(args) {
+  const cwd = process.cwd();
+  const rihalDir = path.join(cwd, '.rihal');
+
+  if (!fs.existsSync(rihalDir)) {
+    console.error(`❌ No .rihal/ directory found in ${cwd}`);
+    console.error(`   Run 'rihal-code install' first.`);
+    process.exit(1);
+  }
+
+  const requested = args[0];
+
+  if (!requested) {
+    // Show current + available modes
+    const config = loadConfig(cwd);
+    const current = config.communication_mode || 'guided';
+    console.log(`\n🕌 Communication mode: ${current}\n`);
+    for (const mode of VALID_COMMUNICATION_MODES) {
+      const marker = mode === current ? ' ← current' : '';
+      console.log(`  • ${mode}${marker}`);
+      console.log(`     ${MODE_DESCRIPTIONS[mode]}`);
+      console.log();
+    }
+    console.log(`Usage: rihal-code set-mode <${[...VALID_COMMUNICATION_MODES].join('|')}>`);
+    console.log();
+    return;
+  }
+
+  // Delegate to the shared config setter — it handles validation,
+  // typo suggestions, and atomic writes.
+  const previous = loadConfig(cwd).communication_mode || 'guided';
+  const result = setConfigValue(cwd, 'communication_mode', requested);
+  if (!result.ok) {
+    console.error(`\n❌ ${result.error}`);
+    if (result.suggestion) {
+      console.error(`   Did you mean '${result.suggestion}'?`);
+    }
+    console.error();
+    process.exit(1);
+  }
+
+  console.log(`\n✅ Communication mode: ${previous} → ${requested}`);
+  console.log();
+  console.log(`   ${MODE_DESCRIPTIONS[requested]}`);
+  console.log();
+
+  if (requested === 'yolo') {
+    console.log(`   ⚠ Note: destructive operations (github-sync, uninstall,`);
+    console.log(`     force push) still require explicit confirmation unless`);
+    console.log(`     --force-yolo / --yes is passed.`);
+    console.log();
+  }
+};

package/cli/set-profile.js

@@ -0,0 +1,80 @@
+/**
+ * rihal-code set-profile — change the model profile for the current project
+ *
+ * Usage:
+ *   npx @hanzlahabib/rihal-code set-profile balanced
+ *   npx @hanzlahabib/rihal-code set-profile quality
+ *   npx @hanzlahabib/rihal-code set-profile budget
+ *   npx @hanzlahabib/rihal-code set-profile inherit
+ *   npx @hanzlahabib/rihal-code set-profile                  # show current
+ *
+ * This is a thin wrapper over `rihal-code config model_profile <name>`.
+ * All config read/write goes through cli/lib/config.cjs, which handles
+ * atomic writes, allowlist validation, and typo suggestions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  listProfiles,
+  getProfile,
+  getResolvedMapForProfile,
+  formatMapAsTable,
+  getProjectProfile,
+} = require('./lib/model-profiles.cjs');
+const { setConfigValue, getConfigValue } = require('./lib/config.cjs');
+
+module.exports = function setProfile(args) {
+  const cwd = process.cwd();
+  const rihalDir = path.join(cwd, '.rihal');
+
+  if (!fs.existsSync(rihalDir)) {
+    console.error(`❌ No .rihal/ directory found in ${cwd}`);
+    console.error(`   Run 'npx @hanzlahabib/rihal-code install' first.`);
+    process.exit(1);
+  }
+
+  const requested = args[0];
+  const available = listProfiles();
+
+  if (!requested) {
+    // Show current profile + available options
+    const current = getProjectProfile(cwd);
+    console.log(`\n🕌 Current profile: ${current.profile}\n`);
+    if (Object.keys(current.overrides).length > 0) {
+      console.log(`   Overrides:`);
+      for (const [agent, model] of Object.entries(current.overrides)) {
+        console.log(`     ${agent} → ${model}`);
+      }
+      console.log();
+    }
+    console.log(`Available profiles:`);
+    for (const name of available) {
+      const p = getProfile(name);
+      const marker = name === current.profile ? ' ← current' : '';
+      console.log(`  • ${name}${marker}`);
+      console.log(`    ${p.description}`);
+    }
+    console.log(`\nUsage: npx @hanzlahabib/rihal-code set-profile <name>`);
+    return;
+  }
+
+  const previous = getConfigValue(cwd, 'model_profile') || '(default)';
+
+  const result = setConfigValue(cwd, 'model_profile', requested);
+  if (!result.ok) {
+    console.error(`❌ ${result.error}`);
+    if (result.suggestion) {
+      console.error(`   Did you mean '${result.suggestion}'?`);
+    }
+    console.error(`   Available: ${available.join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`\n✅ Profile changed: ${previous} → ${requested}\n`);
+
+  // Show the new resolved map
+  const map = getResolvedMapForProfile(requested);
+  console.log(formatMapAsTable(map));
+  console.log();
+};

package/cli/show-model.js

@@ -0,0 +1,82 @@
+/**
+ * rihal-code show-model — print the resolved model for an agent (or all agents)
+ *
+ * Usage:
+ *   npx @hanzlahabib/rihal-code show-model              # all agents in current profile
+ *   npx @hanzlahabib/rihal-code show-model waleed       # single agent
+ *   npx @hanzlahabib/rihal-code show-model --profile=quality   # different profile
+ */
+
+const {
+  listProfiles,
+  getProfile,
+  resolveModelForAgent,
+  getResolvedMapForProfile,
+  formatMapAsTable,
+  getProjectProfile,
+} = require('./lib/model-profiles.cjs');
+
+function parseArgs(args) {
+  const result = { agent: null, profile: null };
+  for (const arg of args) {
+    if (arg.startsWith('--profile=')) {
+      result.profile = arg.slice('--profile='.length);
+    } else if (arg.startsWith('--agent=')) {
+      result.agent = arg.slice('--agent='.length);
+    } else if (!arg.startsWith('--')) {
+      result.agent = arg;
+    }
+  }
+  return result;
+}
+
+module.exports = function showModel(args) {
+  const parsed = parseArgs(args);
+  const project = getProjectProfile();
+  const profile = parsed.profile || project.profile;
+
+  if (!listProfiles().includes(profile)) {
+    console.error(`❌ Unknown profile '${profile}'`);
+    console.error(`   Available: ${listProfiles().join(', ')}`);
+    process.exit(1);
+  }
+
+  const profileDef = getProfile(profile);
+
+  if (parsed.agent) {
+    // Single agent
+    try {
+      const model = resolveModelForAgent(parsed.agent, {
+        profile,
+        overrides: parsed.profile ? {} : project.overrides,
+      });
+      console.log(`${parsed.agent} (profile: ${profile}) → ${model ?? 'inherit (runtime picks)'}`);
+    } catch (e) {
+      console.error(`❌ ${e.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // All agents
+  console.log(`\n🕌 Profile: ${profile}`);
+  console.log(`   ${profileDef.description}\n`);
+
+  const map = getResolvedMapForProfile(profile);
+
+  // Apply project overrides if we're showing the current project profile
+  if (!parsed.profile && Object.keys(project.overrides).length > 0) {
+    console.log(`   Overrides applied:`);
+    for (const [agent, rawModel] of Object.entries(project.overrides)) {
+      const resolved = resolveModelForAgent(agent, {
+        profile,
+        overrides: project.overrides,
+      });
+      map[agent] = resolved;
+      console.log(`     ${agent} → ${rawModel} (resolved: ${resolved ?? 'inherit'})`);
+    }
+    console.log();
+  }
+
+  console.log(formatMapAsTable(map));
+};

package/cli/team.js

@@ -0,0 +1,35 @@
+/**
+ * rihal-code team — list the team roster
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+module.exports = function team(args, { packageRoot }) {
+  const digestDir = path.join(packageRoot, 'rihal/digests');
+
+  if (!fs.existsSync(digestDir)) {
+    console.error('Agent digests not found. Is the package installed correctly?');
+    process.exit(1);
+  }
+
+  const files = fs.readdirSync(digestDir).filter((f) => f.endsWith('.md') && f !== 'README.md');
+
+  console.log(`\n🕌 Rihal Code Team Roster (${files.length} agents)\n`);
+  console.log('─'.repeat(80));
+
+  for (const file of files.sort()) {
+    const content = fs.readFileSync(path.join(digestDir, file), 'utf8');
+    const firstLine = content.split('\n')[0].replace(/^#\s*/, '');
+    const arabic = (content.match(/\*\*Arabic:\*\*\s*(.+)/) || [])[1] || '';
+    const authority = (content.match(/\*\*Authority:\*\*\s*(.+)/) || [])[1] || '';
+
+    console.log(`${firstLine.padEnd(45)} ${arabic.padEnd(15)}`);
+    if (authority) console.log(`  → ${authority.slice(0, 70)}`);
+    console.log();
+  }
+
+  console.log('─'.repeat(80));
+  console.log(`\nFor full agent details: cat rihal/digests/{agent}.md`);
+  console.log(`For full skill: rihal/skills/agents/{agent-dir}/SKILL.md\n`);
+};