nfo-cli 0.0.3 → 0.0.5

package/src/musicians/message.ts

@@ -1,99 +0,0 @@
-import { sendKeys, sessionName } from '../tmux.js';
-import { readState } from '../state.js';
-import { findMusicianStrict } from './lookup.js';
-import {
-  setMusicianStatus,
-  touchMusicianActivity,
-} from '../state-updaters.js';
-import {
-  countPendingMusicianMessages,
-  formatQueuedMusicianMessages,
-  listPendingMusicianMessages,
-  markMusicianMessageDelivered,
-  queueMusicianMessage,
-  type MusicianMessageDelivery,
-} from './message-log.js';
-
-export interface MessageMusicianOptions {
-  orchestraId: string;
-  musicianId: string;
-  message: string;
-}
-
-export interface MessageMusicianResult {
-  ok: true;
-  delivery: 'immediate' | 'queued';
-  message_id: string;
-  pending_messages: number;
-}
-
-async function deliverPendingMessages(
-  orchestraId: string,
-  musicianId: string,
-  delivery: MusicianMessageDelivery,
-): Promise<number> {
-  const state = await readState(orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${orchestraId}`);
-  }
-  const musician = findMusicianStrict(state, musicianId);
-  const pending = await listPendingMusicianMessages(orchestraId, musicianId);
-  if (pending.length === 0) {
-    return 0;
-  }
-
-  const target = `${sessionName(orchestraId)}:${musician.tmux_window_id}`;
-  const message = formatQueuedMusicianMessages(pending);
-  await sendKeys(target, message, true);
-
-  const deliveredAt = new Date().toISOString();
-  for (const pendingMessage of pending) {
-    await markMusicianMessageDelivered(
-      orchestraId,
-      musicianId,
-      pendingMessage.messageId,
-      delivery,
-      deliveredAt,
-    );
-  }
-  await touchMusicianActivity(orchestraId, musicianId, deliveredAt);
-  return pending.length;
-}
-
-export async function messageMusician(opts: MessageMusicianOptions): Promise<MessageMusicianResult> {
-  const state = await readState(opts.orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${opts.orchestraId}`);
-  }
-  const musician = findMusicianStrict(state, opts.musicianId);
-  const queued = await queueMusicianMessage(opts.orchestraId, opts.musicianId, opts.message);
-
-  if (musician.status === 'idle') {
-    const delivery: MusicianMessageDelivery = (await countPendingMusicianMessages(
-      opts.orchestraId,
-      opts.musicianId,
-    )) === 1 ? 'immediate' : 'queued-drain';
-    await deliverPendingMessages(opts.orchestraId, opts.musicianId, delivery);
-    await setMusicianStatus(opts.orchestraId, opts.musicianId, 'working');
-    return {
-      ok: true,
-      delivery: 'immediate',
-      message_id: queued.messageId,
-      pending_messages: 0,
-    };
-  }
-
-  return {
-    ok: true,
-    delivery: 'queued',
-    message_id: queued.messageId,
-    pending_messages: await countPendingMusicianMessages(opts.orchestraId, opts.musicianId),
-  };
-}
-
-export async function drainQueuedMusicianMessages(
-  orchestraId: string,
-  musicianId: string,
-): Promise<number> {
-  return deliverPendingMessages(orchestraId, musicianId, 'queued-drain');
-}

package/src/musicians/query.ts

@@ -1,19 +0,0 @@
-import { capturePane, sessionName } from '../tmux.js';
-import { readState } from '../state.js';
-import { findMusicianStrict } from './lookup.js';
-
-export interface QueryMusicianOptions {
-  orchestraId: string;
-  musicianId: string;
-  lines?: number;
-}
-
-export async function queryMusician(opts: QueryMusicianOptions): Promise<string> {
-  const state = await readState(opts.orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${opts.orchestraId}`);
-  }
-  const musician = findMusicianStrict(state, opts.musicianId);
-  const target = `${sessionName(opts.orchestraId)}:${musician.tmux_window_id}`;
-  return capturePane(target, opts.lines ?? 80);
-}

package/src/musicians/spawn.ts

@@ -1,139 +0,0 @@
-import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { execa } from "execa";
-import { addMusician } from "../state-updaters.js";
-import { readState } from "../state.js";
-import { orchestraDir, worktreesDir } from "../config.js";
-import { addWorktree } from "../worktree.js";
-import { claudeFlagsForLevel } from "../permission.js";
-import { respawnPane, sessionName, setPaneOption } from "../tmux.js";
-import { MUSICIAN_ROLE_PROMPT_V1 } from "../prompts/musician-role.js";
-import { buildMusicianInitialPrompt } from "../prompts/tool-discipline.js";
-import { nextMusicianId } from "./ids.js";
-import { buildClaudeCommand } from "../claude-command.js";
-import { writeMusicianMcpConfig } from "../mcp/config.js";
-
-export interface CreateMusicianOptions {
-  orchestraId: string;
-  name: string;
-  task: string;
-  worktree?: boolean; // default true
-  branchFrom?: string; // default HEAD
-  model: "sonnet" | "haiku";
-  dryRun?: boolean; // skip launching claude; useful for tests
-}
-
-export type CreateMusicianResult = {
-  musician_id: string;
-  worktree_path: string | null;
-  branch: string | null;
-  tmux_window_id: string;
-};
-
-export async function createMusician(
-  opts: CreateMusicianOptions,
-): Promise<CreateMusicianResult> {
-  const state = await readState(opts.orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${opts.orchestraId}`);
-  }
-
-  const musicianId = nextMusicianId(state);
-  const useWorktree = opts.worktree !== false;
-
-  let workingDir: string;
-  let worktreePath: string | null = null;
-  let branch: string | null = null;
-  if (useWorktree) {
-    worktreePath = join(worktreesDir(opts.orchestraId), musicianId);
-    branch = `nfo/${musicianId}`;
-    await addWorktree({
-      repoRoot: state.project_path,
-      path: worktreePath,
-      branch,
-      baseRef: opts.branchFrom,
-    });
-    workingDir = worktreePath;
-  } else {
-    workingDir = state.project_path;
-  }
-
-  const promptFile = join(
-    orchestraDir(opts.orchestraId),
-    `musician-${musicianId}-prompt.md`,
-  );
-  await writeFile(promptFile, MUSICIAN_ROLE_PROMPT_V1, "utf8");
-
-  const session = sessionName(opts.orchestraId);
-  const winLabel = `mus-${musicianId}-${sanitiseName(opts.name)}`;
-  const { stdout: tmuxWindowId } = await execa("tmux", [
-    "new-window",
-    "-t",
-    session,
-    "-n",
-    winLabel,
-    "-c",
-    workingDir,
-    "-d",
-    "-P",
-    "-F",
-    "#{window_id}",
-  ]);
-
-  if (!opts.dryRun) {
-    const mcpConfigPath = await writeMusicianMcpConfig(
-      opts.orchestraId,
-      musicianId,
-    );
-    const flags = claudeFlagsForLevel(state.permission_level);
-    const cmd = buildClaudeCommand({
-      flags,
-      mcpConfigPath,
-      promptFile,
-      prompt: buildMusicianInitialPrompt(opts.task),
-      model: opts.model,
-    });
-    await setPaneOption(
-      `${session}:${tmuxWindowId.trim()}`,
-      "remain-on-exit",
-      "on",
-    );
-    await respawnPane(`${session}:${tmuxWindowId.trim()}`, cmd);
-  } else {
-    await writeMusicianMcpConfig(opts.orchestraId, musicianId);
-  }
-
-  const now = new Date().toISOString();
-  await addMusician(opts.orchestraId, {
-    id: musicianId,
-    name: opts.name,
-    task_summary: opts.task.slice(0, 200),
-    status: "working",
-    pending_permission: null,
-    tmux_window_id: tmuxWindowId.trim(),
-    claude_session_id: null,
-    worktree_path: worktreePath,
-    branch,
-    spawned_at: now,
-    last_activity: now,
-    model: opts.model,
-  });
-
-  return {
-    musician_id: musicianId,
-    worktree_path: worktreePath,
-    branch,
-    tmux_window_id: tmuxWindowId.trim(),
-  };
-}
-
-function sanitiseName(name: string): string {
-  return (
-    name
-      .toLowerCase()
-      .replace(/[^a-z0-9-]+/g, "-")
-      .replace(/-+/g, "-")
-      .replace(/^-|-$/g, "")
-      .slice(0, 32) || "musician"
-  );
-}

package/src/notes.ts

@@ -1,39 +0,0 @@
-import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { notesDir } from './config.js';
-
-function ensureSafeFilename(filename: string): void {
-  if (!filename || /[\/\\]/.test(filename) || filename.includes('..')) {
-    throw new Error(`invalid filename: ${filename}`);
-  }
-}
-
-export async function noteWrite(
-  orchestraId: string,
-  filename: string,
-  content: string,
-): Promise<void> {
-  ensureSafeFilename(filename);
-  const dir = notesDir(orchestraId);
-  await mkdir(dir, { recursive: true });
-  await writeFile(join(dir, filename), content, 'utf8');
-}
-
-export async function noteRead(orchestraId: string, filename: string): Promise<string> {
-  ensureSafeFilename(filename);
-  const file = join(notesDir(orchestraId), filename);
-  if (!existsSync(file)) {
-    return '';
-  }
-  return readFile(file, 'utf8');
-}
-
-export async function noteList(orchestraId: string): Promise<string[]> {
-  const dir = notesDir(orchestraId);
-  if (!existsSync(dir)) {
-    return [];
-  }
-  const entries = await readdir(dir, { withFileTypes: true });
-  return entries.filter((e) => { return e.isFile(); }).map((e) => { return e.name; });
-}

package/src/notify.ts

@@ -1,62 +0,0 @@
-import { execa } from 'execa';
-
-export interface NotifyOptions {
-  pendingCount: number;
-  platform?: NodeJS.Platform;
-  bell?: (text: string) => void;
-  spawn?: (bin: string, args: string[]) => Promise<unknown>;
-}
-
-function defaultBell(text: string): void {
-  process.stdout.write(text);
-}
-
-async function defaultSpawn(bin: string, args: string[]): Promise<unknown> {
-  return execa(bin, args);
-}
-
-function pluralise(count: number): string {
-  if (count === 1) {
-    return '1 musician awaiting permission';
-  }
-  return `${count} musicians awaiting permission`;
-}
-
-/**
- * Fire a single notification: ring the terminal bell and (best-effort) spawn
- * the platform's desktop notifier. All errors are swallowed — a missing
- * notify-send / osascript / etc. must not break the orchestra.
- */
-export async function notifyAwaitingPermission(opts: NotifyOptions): Promise<void> {
-  const bell = opts.bell ?? defaultBell;
-  const spawn = opts.spawn ?? defaultSpawn;
-  const platform = opts.platform ?? process.platform;
-  const message = pluralise(opts.pendingCount);
-
-  try {
-    bell('\x07');
-  } catch {
-    // Swallow — a broken stdout sink should never abort.
-  }
-
-  if (platform === 'linux') {
-    try {
-      await spawn('notify-send', ['NFO', message]);
-    } catch {
-      // notify-send may not be installed — best-effort only.
-    }
-    return;
-  }
-
-  if (platform === 'darwin') {
-    const script = `display notification "${message}" with title "NFO"`;
-    try {
-      await spawn('osascript', ['-e', script]);
-    } catch {
-      // osascript should exist on macOS but swallow defensively.
-    }
-    return;
-  }
-
-  // Unknown platform (win32, freebsd, etc.) — bell-only.
-}

package/src/orchestrator/report-back.ts

@@ -1,33 +0,0 @@
-import { sendKeys, sessionName } from '../tmux.js';
-
-export interface MusicianDoneReport {
-  musicianId: string;
-  musicianName: string;
-  summary: string;
-  nextSteps?: string | null;
-}
-
-export function formatMusicianDonePrompt(report: MusicianDoneReport): string {
-  const nextSteps = report.nextSteps?.trim()
-    ? `\nSuggested next steps from the Musician:\n${report.nextSteps.trim()}\n`
-    : '';
-
-  return `Musician ${report.musicianId} (${report.musicianName}) reported done and is now idle.
-
-Summary:
-${report.summary}
-${nextSteps}
-Resolve this now with an NFO tool call only:
-- If the work is good enough, call dismiss_musician({ musician_id: ${JSON.stringify(report.musicianId)} }).
-- If it needs another pass, call message_musician({ musician_id: ${JSON.stringify(report.musicianId)}, message: "..." }).
-
-Do not leave this Musician idle without either dismissing it or sending the next iteration.
-A plain-text acknowledgement is invalid here.`;
-}
-
-export async function notifyOrchestratorOfDoneReport(
-  orchestraId: string,
-  report: MusicianDoneReport,
-): Promise<void> {
-  await sendKeys(`${sessionName(orchestraId)}:0`, formatMusicianDonePrompt(report), true);
-}

package/src/permission.ts

@@ -1,30 +0,0 @@
-export const PERMISSION_LEVELS = ['auto', 'autonomous', 'supervised', 'strict'] as const;
-export type PermissionLevel = (typeof PERMISSION_LEVELS)[number];
-
-export function isPermissionLevel(s: string): s is PermissionLevel {
-  return (PERMISSION_LEVELS as readonly string[]).includes(s);
-}
-
-export function claudeFlagsForLevel(level: PermissionLevel): string[] {
-  switch (level) {
-    case 'auto':
-      // Spec §5.2 + §12.2 open question: exact bypass flag is `--dangerously-skip-permissions`
-      // in current Claude Code releases. If a future release renames it, update here.
-      return ['--dangerously-skip-permissions'];
-    case 'autonomous':
-      return ['--permission-mode', 'acceptEdits'];
-    case 'supervised':
-      return ['--permission-mode', 'default'];
-    case 'strict':
-      return ['--permission-mode', 'plan'];
-  }
-}
-
-export const AUTO_CONFIRM_PHRASE = 'I understand';
-
-export const AUTO_WARNING = `⚠ AUTO mode disables all permission checks.
-Musicians can execute arbitrary shell commands, modify files anywhere on
-this system, and access the network without asking. Worktrees limit but
-do not contain risky operations. Use this only in trusted sandboxes or
-when you accept these risks.
-Type "${AUTO_CONFIRM_PHRASE}" to continue.`;

package/src/project-key.ts

@@ -1,12 +0,0 @@
-import { createHash } from 'node:crypto';
-import { basename } from 'node:path';
-
-export function projectKeyFromPath(absolutePath: string): string {
-  const hash = createHash('sha1').update(absolutePath).digest('hex').slice(0, 10);
-  const name = basename(absolutePath)
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '');
-  return `${hash}-${name || 'project'}`;
-}

package/src/prompts/musician-role.ts

@@ -1,22 +0,0 @@
-import { MUSICIAN_TOOL_DISCIPLINE } from './tool-discipline.js';
-
-export const MUSICIAN_ROLE_PROMPT_V1 = `You are a Musician in an NFO orchestra.
-
-You were spawned by the Orchestrator with a specific task. The user typing into
-your pane is debugging / observing — usually the user does NOT direct you;
-the Orchestrator does. Treat new user messages as either Orchestrator
-hand-offs or out-of-band human guidance, and use judgment.
-
-Your workspace is a dedicated git worktree, so file edits are isolated from
-other Musicians. When you finish the task you were spawned with, call the
-\`report_done\` MCP tool with a concise summary and optional next steps. After
-that, stay alive while the Orchestrator reviews your report. NFO may batch
-queued follow-up messages and deliver them right after \`report_done\`; if the
-Orchestrator is satisfied, it may dismiss you instead.
-
-${MUSICIAN_TOOL_DISCIPLINE}
-
-You also have the full NFO MCP tool surface (\`spawn_musician\`,
-\`message_musician\`, etc.). Avoid spawning sub-Musicians unless the
-Orchestrator explicitly asks you to. Keep coordination centralised.
-`;

package/src/prompts/orchestrator-role.ts

@@ -1,60 +0,0 @@
-import { ORCHESTRATOR_TOOL_DISCIPLINE } from "./tool-discipline.js";
-
-export const ORCHESTRATOR_ROLE_PROMPT_V1 = `You are the Orchestrator of an NFO orchestra.
-
-NFO (NoFluffOrchestra) is a TUI for multi-agent work on the user's repository.
-You coordinate Musicians (other Claude Code agents) via the NFO MCP tools.
-
-Available NFO tools (in addition to your normal Claude Code tools):
-
-  spawn_musician({ name, task, worktree?, branch_from?, model? })
-    Create a Musician with the given task. By default the Musician runs in a
-    fresh git worktree off HEAD. Pass worktree=false for trivially isolated
-    work (e.g., docs-only) that doesn't need an isolated branch. Returns the
-    musician_id. Provide a model to be used by the Musician, otherwise it defaults to sonnet.
-    For trivial tasks Haiku is a good choice; for complex coding work, Sonnet is better.
-
-  message_musician({ musician_id, message })
-    Send a message to a Musician. If the Musician is idle, NFO delivers it
-    immediately. If the Musician is still working, NFO queues it and delivers
-    it automatically on the next idle boundary.
-
-  query_musician({ musician_id, lines? })
-    Read the most recent visible output from the Musician's pane. Use this
-    sparingly — capture-pane is heuristic and may include rendering artifacts.
-
-  list_musicians()
-    Return all currently-active Musicians with their status.
-
-  dismiss_musician({ musician_id, archive_worktree? })
-    Tear down a Musician. The worktree is archived under
-    .../archive/<musician_id>/worktree (the branch is preserved). Pass
-    archive_worktree=false to drop the worktree entirely. By default drop the worktree. Ask
-    the user before archiving, as these can accumulate and consume disk space.
-
-  note_write({ filename, content }) / note_read({ filename }) / note_list()
-    Your private project memory under ~/.config/nfo/projects/<key>/notes/.
-    On every fresh Orchestrator session, the contents of notes/overview.md
-    and notes/decisions.md are loaded into your context automatically.
-    Use these to record decisions, open questions, and durable project
-    understanding the user would want you to remember next session.
-
-Coordination guidance:
-
-- ${ORCHESTRATOR_TOOL_DISCIPLINE.trim().replace(/\n/g, "\n  ")}
-- For agent coordination, PREFER the NFO MCP tools over Claude Code's built-in
-  Task tool. The user tracks Musician work through NFO; Task spawns are invisible
-  to NFO.
-- Worktrees solve concurrent file-edit safety, not API coupling. If two
-  Musicians' outputs need to be wired together, sequence the work, or spawn an
-  integration Musician afterward.
-- The orchestra's permission level applies to every Musician you spawn.
-- Prefer concise follow-up nudges. NFO persists them in JSONL and batches any
-  backlog before a Musician truly becomes idle again.
-- When a Musician calls \`report_done\` and no queued follow-up is waiting, NFO
-  pushes that completion back into your Claude session. Review the report
-  promptly and either dismiss the Musician or send the next iteration.
-- Project-level guidance in CLAUDE.md still applies; respect it.
-- You can use Superpowers if present but make sure that works are delegated to 
-  Musicians in the end if subagent driven development is picked by the user.
-`;

package/src/prompts/tool-discipline.ts

@@ -1,35 +0,0 @@
-export const ORCHESTRATOR_TOOL_DISCIPLINE = `Tool discipline (mandatory):
-
-- Use the NFO MCP tools for all musician coordination and orchestra-local memory.
-- Never merely say that you will spawn, message, query, list, dismiss, or note
-  something later. Call the corresponding NFO tool in the same turn.
-- Do not use Claude Code's built-in Task tool for Musician coordination; those
-  agents are invisible to NFO.
-- When a Musician reports back, resolve it in the same turn with an NFO tool
-  call (usually \`dismiss_musician\` or \`message_musician\`). A prose-only
-  acknowledgement is non-compliant.
-`;
-
-export const MUSICIAN_TOOL_DISCIPLINE = `Tool discipline (mandatory):
-
-- Use NFO MCP tools for orchestra coordination. Plain-text status reports are
-  not a valid handoff.
-- When your assigned task is complete and ready for Orchestrator review, your
-  next action must be \`report_done({ summary, next_steps? })\`.
-- Do not end with "done", "finished", or similar prose instead of calling
-  \`report_done\`.
-- After \`report_done\`, wait for the Orchestrator to send the next task or
-  dismiss you.
-`;
-
-export function buildMusicianInitialPrompt(task: string): string {
-  const trimmedTask = task.trim();
-  const body = trimmedTask.length > 0 ? trimmedTask : task;
-
-  return `${body}
-
-NFO operating contract (mandatory):
-- Use the NFO MCP tools for orchestra coordination.
-- When you finish this task and are ready to hand it back, call \`report_done({ summary, next_steps? })\` instead of replying with a plain-text completion message.
-- After \`report_done\`, wait for the Orchestrator to message you again or dismiss you.`;
-}

package/src/repo.ts

@@ -1,14 +0,0 @@
-import { execa } from 'execa';
-
-export async function resolveRepoRoot(cwd: string): Promise<string | null> {
-  try {
-    const { stdout } = await execa('git', ['rev-parse', '--show-toplevel'], {
-      cwd,
-      reject: false,
-    });
-    const trimmed = stdout.trim();
-    return trimmed.length > 0 ? trimmed : null;
-  } catch {
-    return null;
-  }
-}

package/src/shell-quote.ts

@@ -1,7 +0,0 @@
-export function shellQuote(value: string): string {
-  if (value.length === 0) {
-    return "''";
-  }
-
-  return `'${value.replace(/'/g, `'\"'\"'`)}'`;
-}