@fuzeelogik/myflo 1.0.0-rc.4

package/lib/memory-cmd.js

@@ -0,0 +1,148 @@
+import {
+  storeEntry,
+  searchEntries,
+  listEntries,
+  getEntry,
+  deleteEntry,
+  namespaceStats,
+  listNamespaces,
+} from './memory-store.js';
+
+export async function memoryCommand(args) {
+  const [sub = 'help', ...rest] = args;
+  if (sub === 'help' || sub === '--help' || sub === '-h') return printHelp();
+  if (sub === 'store') return storeCommand(rest);
+  if (sub === 'search') return searchCommand(rest);
+  if (sub === 'list') return listCommand(rest);
+  if (sub === 'get') return getCommand(rest);
+  if (sub === 'delete') return deleteCommand(rest);
+  if (sub === 'namespaces' || sub === 'ns') return namespacesCommand(rest);
+  console.error(`flo memory: unknown subcommand '${sub}'`);
+  console.error(`Available: store, search, list, get, delete, namespaces, help`);
+  process.exit(2);
+}
+
+function printHelp() {
+  console.log(`flo memory — file-backed JSON store at ~/.flo/memory/
+
+Usage:
+  flo memory store --value <text> [--key <k>] [--namespace <ns>] [--tags a,b]
+  flo memory search <query> [--namespace <ns>] [--tags a,b] [--limit N] [--json]
+  flo memory list [--namespace <ns>] [--limit N] [--json]
+  flo memory get [--id <id> | --key <key>] [--namespace <ns>]
+  flo memory delete --id <id> [--namespace <ns>]
+  flo memory namespaces [--json]
+
+Storage: append-only JSONL per namespace. Deletes use tombstones (history preserved).
+Search: substring + tag scoring. No vector embeddings yet.
+`);
+}
+
+function parseFlags(args) {
+  const out = { positional: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--namespace' || a === '-n') out.namespace = args[++i];
+    else if (a === '--key' || a === '-k') out.key = args[++i];
+    else if (a === '--value' || a === '-v') out.value = args[++i];
+    else if (a === '--id') out.id = args[++i];
+    else if (a === '--tags') out.tags = (args[++i] || '').split(',').map((t) => t.trim()).filter(Boolean);
+    else if (a === '--limit') out.limit = Number(args[++i]);
+    else if (!a.startsWith('--')) out.positional.push(a);
+  }
+  return out;
+}
+
+async function storeCommand(args) {
+  const opts = parseFlags(args);
+  if (!opts.value && opts.positional.length === 0) {
+    console.error(`flo memory store: missing --value (or positional text)`);
+    process.exit(2);
+  }
+  const value = opts.value ?? opts.positional.join(' ');
+  const entry = await storeEntry({
+    namespace: opts.namespace,
+    key: opts.key,
+    value,
+    tags: opts.tags,
+  });
+  if (opts.json) console.log(JSON.stringify(entry));
+  else console.log(`flo memory store: ${entry.namespace}/${entry.id} (${value.length} chars)`);
+}
+
+async function searchCommand(args) {
+  const opts = parseFlags(args);
+  const query = opts.positional.join(' ');
+  if (!query && (!opts.tags || !opts.tags.length)) {
+    console.error(`flo memory search: missing query or --tags`);
+    process.exit(2);
+  }
+  const results = await searchEntries({
+    namespace: opts.namespace,
+    query,
+    tags: opts.tags || [],
+    limit: opts.limit || 20,
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  if (!results.length) { console.log(`flo memory search: 0 results`); return; }
+  for (const r of results) {
+    const head = r.value.split('\n')[0].slice(0, 80);
+    console.log(`[score=${r._score}] ${r.namespace}/${r.id} ${r.key ? `(${r.key})` : ''}`);
+    console.log(`  ${head}${r.value.length > 80 ? '…' : ''}`);
+    if (r.tags?.length) console.log(`  tags: ${r.tags.join(', ')}`);
+  }
+}
+
+async function listCommand(args) {
+  const opts = parseFlags(args);
+  const entries = await listEntries({
+    namespace: opts.namespace || 'default',
+    limit: opts.limit || 50,
+  });
+  if (opts.json) { console.log(JSON.stringify(entries, null, 2)); return; }
+  if (!entries.length) {
+    console.log(`flo memory list: no entries in ${opts.namespace || 'default'}`);
+    return;
+  }
+  for (const e of entries) {
+    const head = e.value.split('\n')[0].slice(0, 80);
+    console.log(`${e.id}  ${e.key ?? '—'}  ${head}${e.value.length > 80 ? '…' : ''}`);
+  }
+}
+
+async function getCommand(args) {
+  const opts = parseFlags(args);
+  const e = await getEntry({ namespace: opts.namespace, id: opts.id, key: opts.key });
+  if (!e) { console.error(`flo memory get: not found`); process.exit(1); }
+  if (opts.json) console.log(JSON.stringify(e, null, 2));
+  else console.log(e.value);
+}
+
+async function deleteCommand(args) {
+  const opts = parseFlags(args);
+  if (!opts.id) {
+    console.error(`flo memory delete: missing --id`);
+    process.exit(2);
+  }
+  await deleteEntry({ namespace: opts.namespace, id: opts.id });
+  console.log(`flo memory delete: tombstoned ${opts.namespace || 'default'}/${opts.id}`);
+}
+
+async function namespacesCommand(args) {
+  const opts = parseFlags(args);
+  const stats = await namespaceStats();
+  if (opts.json) { console.log(JSON.stringify(stats, null, 2)); return; }
+  if (!stats.length) { console.log(`flo memory: no namespaces yet`); return; }
+  console.log(`namespace                count   last entry`);
+  console.log(`-----------------------  ------  --------------------`);
+  for (const s of stats) {
+    const ns = s.namespace.padEnd(23).slice(0, 23);
+    const count = String(s.count).padStart(6);
+    const last = s.lastEntryAt ? s.lastEntryAt.slice(0, 19).replace('T', ' ') : '—';
+    console.log(`${ns}  ${count}  ${last}`);
+  }
+}

package/lib/memory-store.js

@@ -0,0 +1,258 @@
+// Memory store with two backends:
+//   - jsonl  (default) — file-backed JSONL per namespace under ~/.flo/memory/<ns>.jsonl
+//                        Pure JS, no native deps, BM25 ranking. Zero install cost.
+//   - agentdb         — SQLite-backed via @myflo/memory's SqlJsBackend. FTS5
+//                        keyword search, optional vector embeddings, scales further.
+//
+// Select via FLO_MEMORY_BACKEND env var or { backend } option on each call.
+// Public API is identical regardless of backend.
+
+import { mkdir, readFile, writeFile, appendFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+const FLO_HOME = process.env.FLO_HOME || join(homedir(), '.flo');
+const MEMORY_DIR = join(FLO_HOME, 'memory');
+
+function currentBackend(opts) {
+  const explicit = opts && opts.backend;
+  if (explicit) return explicit;
+  return process.env.FLO_MEMORY_BACKEND === 'agentdb' ? 'agentdb' : 'jsonl';
+}
+
+async function agentdb() {
+  // Lazy-load — only required when actually selecting agentdb backend
+  return await import('./memory-backend-agentdb.js');
+}
+
+function nsPath(ns) {
+  return join(MEMORY_DIR, `${sanitizeNs(ns)}.jsonl`);
+}
+
+function sanitizeNs(ns) {
+  return String(ns || 'default').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64) || 'default';
+}
+
+async function ensureDir() {
+  if (!existsSync(MEMORY_DIR)) await mkdir(MEMORY_DIR, { recursive: true });
+}
+
+function newId() {
+  return `${Date.now()}-${randomBytes(3).toString('hex')}`;
+}
+
+export async function storeEntry(input) {
+  if (currentBackend(input) === 'agentdb') return (await agentdb()).storeEntry(input);
+  return storeEntryJsonl(input);
+}
+
+async function storeEntryJsonl({ namespace = 'default', key, value, tags = [], metadata = {} }) {
+  await ensureDir();
+  const entry = {
+    id: newId(),
+    namespace: sanitizeNs(namespace),
+    key: key ?? null,
+    value: String(value ?? ''),
+    tags: Array.isArray(tags) ? tags.map(String) : [],
+    metadata: metadata && typeof metadata === 'object' ? metadata : {},
+    createdAt: new Date().toISOString(),
+    deleted: false,
+  };
+  await appendFile(nsPath(entry.namespace), JSON.stringify(entry) + '\n', 'utf8');
+  return entry;
+}
+
+export async function deleteEntry(input) {
+  if (currentBackend(input) === 'agentdb') return (await agentdb()).deleteEntry(input);
+  return deleteEntryJsonl(input);
+}
+
+async function deleteEntryJsonl({ namespace = 'default', id }) {
+  await ensureDir();
+  const tomb = { id, namespace: sanitizeNs(namespace), deleted: true, deletedAt: new Date().toISOString() };
+  await appendFile(nsPath(tomb.namespace), JSON.stringify(tomb) + '\n', 'utf8');
+}
+
+async function readAllEntries(namespace) {
+  const ns = sanitizeNs(namespace);
+  const file = nsPath(ns);
+  if (!existsSync(file)) return [];
+  let raw = '';
+  try { raw = await readFile(file, 'utf8'); } catch { return []; }
+  const live = new Map();
+  const tombstones = new Set();
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (row.deleted) {
+      tombstones.add(row.id);
+      live.delete(row.id);
+    } else if (!tombstones.has(row.id)) {
+      live.set(row.id, row);
+    }
+  }
+  return [...live.values()].sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+
+export async function listEntries(opts = {}) {
+  if (currentBackend(opts) === 'agentdb') return (await agentdb()).listEntries(opts);
+  const { namespace = 'default', limit = 50 } = opts;
+  const entries = await readAllEntries(namespace);
+  return entries.slice(0, limit);
+}
+
+export async function getEntry(opts = {}) {
+  if (currentBackend(opts) === 'agentdb') return (await agentdb()).getEntry(opts);
+  const { namespace = 'default', id, key } = opts;
+  const entries = await readAllEntries(namespace);
+  if (id) return entries.find((e) => e.id === id) || null;
+  if (key) return entries.find((e) => e.key === key) || null;
+  return null;
+}
+
+// BM25 parameters. Reasonable defaults for short prose entries.
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+
+// Stopwords pruned aggressively — flo memory entries are short, every
+// non-stopword carries signal. Plurals normalized with a simple suffix rule.
+const STOPWORDS = new Set([
+  'a','an','the','is','are','was','were','be','been','being','to','of','in','on','at','for','and','or','but',
+  'with','from','by','as','it','its','this','that','these','those','i','you','we','they','he','she','him',
+  'her','them','us','our','your','my','their','if','then','else','so','not','no','do','does','did','have',
+  'has','had','will','would','can','could','should','may','might','must','shall','about','into','out','up','down',
+]);
+
+function tokenize(text) {
+  if (!text) return [];
+  return String(text)
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/)
+    .filter((t) => t && t.length > 1 && !STOPWORDS.has(t))
+    .map(stem);
+}
+
+function stem(word) {
+  // Tiny rule-based stemmer: drop common English suffixes. Cheap, no Porter
+  // library needed for the cardinality flo deals with.
+  if (word.length <= 3) return word;
+  for (const suffix of ['ization', 'ational', 'tional', 'iveness', 'fulness', 'ousness']) {
+    if (word.endsWith(suffix)) return word.slice(0, -suffix.length);
+  }
+  for (const suffix of ['ization', 'ization', 'ations', 'ations']) {
+    if (word.endsWith(suffix)) return word.slice(0, -suffix.length);
+  }
+  for (const suffix of ['ing', 'ies', 'ied', 'ies', 'ies', 'ous', 'ive']) {
+    if (word.endsWith(suffix) && word.length > suffix.length + 2) return word.slice(0, -suffix.length);
+  }
+  if (word.endsWith('es') && word.length > 4) return word.slice(0, -2);
+  if (word.endsWith('s') && !word.endsWith('ss') && word.length > 3) return word.slice(0, -1);
+  return word;
+}
+
+function buildCorpusStats(entries) {
+  // entries: pre-tokenized [{ id, tokens, tagTokens }]
+  const docFreq = new Map();
+  let totalLen = 0;
+  for (const e of entries) {
+    const unique = new Set(e.tokens);
+    for (const t of unique) docFreq.set(t, (docFreq.get(t) || 0) + 1);
+    totalLen += e.tokens.length;
+  }
+  const N = entries.length;
+  const avgdl = N > 0 ? totalLen / N : 0;
+  return { docFreq, N, avgdl };
+}
+
+function bm25Score(queryTokens, doc, stats) {
+  if (!queryTokens.length || stats.N === 0) return 0;
+  let score = 0;
+  // Term frequency table for this doc
+  const tf = new Map();
+  for (const t of doc.tokens) tf.set(t, (tf.get(t) || 0) + 1);
+  const dl = doc.tokens.length || 1;
+  for (const q of queryTokens) {
+    const f = tf.get(q);
+    if (!f) continue;
+    const df = stats.docFreq.get(q) || 0;
+    // BM25+ idf: log((N - df + 0.5) / (df + 0.5) + 1) — strictly positive
+    const idf = Math.log((stats.N - df + 0.5) / (df + 0.5) + 1);
+    const norm = 1 - BM25_B + BM25_B * (dl / (stats.avgdl || 1));
+    const termScore = idf * ((f * (BM25_K1 + 1)) / (f + BM25_K1 * norm));
+    score += termScore;
+  }
+  return score;
+}
+
+export async function searchEntries(opts = {}) {
+  if (currentBackend(opts) === 'agentdb') return (await agentdb()).searchEntries(opts);
+  return searchEntriesJsonl(opts);
+}
+
+async function searchEntriesJsonl({ namespace, query, tags = [], limit = 20 }) {
+  const namespaces = namespace ? [namespace] : await listNamespaces();
+  const queryTokens = tokenize(query);
+  const wantTags = new Set(tags.map((t) => String(t).toLowerCase()));
+  const out = [];
+
+  for (const ns of namespaces) {
+    const raw = await readAllEntries(ns);
+    // Pre-tokenize every entry for IDF stats
+    const docs = raw.map((e) => ({
+      entry: e,
+      tokens: tokenize(`${e.key || ''} ${e.value}`),
+      tagSet: new Set((e.tags || []).map((t) => String(t).toLowerCase())),
+    }));
+    const stats = buildCorpusStats(docs);
+
+    for (const doc of docs) {
+      const tagOverlap = [...wantTags].filter((t) => doc.tagSet.has(t)).length;
+      const tagBoost = tagOverlap > 0 ? 2 + tagOverlap * 0.5 : 0;
+      const textScore = bm25Score(queryTokens, doc, stats);
+      // Optional small key boost — exact key match is highly intentional
+      const keyBoost = doc.entry.key && query && doc.entry.key.toLowerCase().includes(String(query).toLowerCase()) ? 1.5 : 0;
+      const score = textScore + tagBoost + keyBoost;
+      if (score <= 0) continue;
+      out.push({ ...doc.entry, _score: Number(score.toFixed(4)) });
+    }
+  }
+  out.sort((a, b) => b._score - a._score);
+  return out.slice(0, limit);
+}
+
+// Exported for direct testing
+export const _searchInternals = { tokenize, stem, buildCorpusStats, bm25Score };
+
+export async function listNamespaces(opts = {}) {
+  if (currentBackend(opts) === 'agentdb') return (await agentdb()).listNamespaces();
+  await ensureDir();
+  const entries = await readdir(MEMORY_DIR);
+  return entries
+    .filter((f) => f.endsWith('.jsonl'))
+    .map((f) => f.replace(/\.jsonl$/, ''));
+}
+
+export async function namespaceStats(opts = {}) {
+  if (currentBackend(opts) === 'agentdb') return (await agentdb()).namespaceStats();
+  return namespaceStatsJsonl();
+}
+
+async function namespaceStatsJsonl() {
+  const names = await listNamespaces();
+  const out = [];
+  for (const ns of names) {
+    const entries = await readAllEntries(ns);
+    out.push({
+      namespace: ns,
+      count: entries.length,
+      lastEntryAt: entries[0]?.createdAt || null,
+    });
+  }
+  out.sort((a, b) => (a.lastEntryAt && b.lastEntryAt ? (a.lastEntryAt < b.lastEntryAt ? 1 : -1) : 0));
+  return out;
+}
+
+export const _internal = { FLO_HOME, MEMORY_DIR, sanitizeNs };

package/lib/messages.js

@@ -0,0 +1,119 @@
+// Reads ~/.flo/messages/<recipient>/ mailbox files written by the inbox bridge.
+
+import { readdir, readFile, stat, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const FLO_HOME = process.env.FLO_HOME || join(homedir(), '.flo');
+const MAILBOX_ROOT = join(FLO_HOME, 'messages');
+
+export async function messagesCommand(args) {
+  const [sub = 'help', ...rest] = args;
+  if (sub === 'help' || sub === '--help' || sub === '-h') return printHelp();
+  if (sub === 'list') return listCommand(rest);
+  if (sub === 'read') return readCommand(rest);
+  if (sub === 'archive') return archiveCommand(rest);
+  console.error(`flo messages: unknown subcommand '${sub}'`);
+  console.error(`Available: list, read, archive, help`);
+  process.exit(2);
+}
+
+function printHelp() {
+  console.log(`flo messages — mailbox reader for inbox-bridged markdown drops
+
+Usage:
+  flo messages list [<recipient>] [--json]
+  flo messages read <recipient> <filename> [--json]
+  flo messages archive <recipient> <filename>
+
+Mailboxes live at ~/.flo/messages/<recipient>/. The inbox watcher writes
+into them when a .md drop has 'to: <recipient>' in its frontmatter.
+`);
+}
+
+async function listRecipients() {
+  if (!existsSync(MAILBOX_ROOT)) return [];
+  const entries = await readdir(MAILBOX_ROOT, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+async function listMessages(recipient) {
+  const dir = join(MAILBOX_ROOT, recipient);
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir);
+  const out = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const path = join(dir, name);
+    try {
+      const st = await stat(path);
+      out.push({ recipient, filename: name, path, size: st.size, mtime: st.mtimeMs });
+    } catch {}
+  }
+  return out.sort((a, b) => b.mtime - a.mtime);
+}
+
+async function listCommand(args) {
+  const json = args.includes('--json');
+  const recipient = args.find((a) => !a.startsWith('--'));
+  if (recipient) {
+    const msgs = await listMessages(recipient);
+    if (json) { console.log(JSON.stringify(msgs, null, 2)); return; }
+    if (!msgs.length) { console.log(`flo messages: no messages for '${recipient}'`); return; }
+    for (const m of msgs) {
+      console.log(`${m.filename}  (${m.size}b, ${new Date(m.mtime).toISOString()})`);
+    }
+    return;
+  }
+  // No recipient: list all
+  const recipients = await listRecipients();
+  const summary = [];
+  for (const r of recipients) {
+    const msgs = await listMessages(r);
+    summary.push({ recipient: r, count: msgs.length });
+  }
+  if (json) { console.log(JSON.stringify(summary, null, 2)); return; }
+  if (!summary.length) { console.log(`flo messages: no mailboxes yet`); return; }
+  console.log(`recipient                count`);
+  console.log(`-----------------------  -----`);
+  for (const s of summary) {
+    console.log(`${s.recipient.padEnd(23).slice(0, 23)}  ${String(s.count).padStart(5)}`);
+  }
+}
+
+async function readCommand(args) {
+  const json = args.includes('--json');
+  const positional = args.filter((a) => !a.startsWith('--'));
+  if (positional.length < 2) {
+    console.error(`flo messages read: usage: flo messages read <recipient> <filename>`);
+    process.exit(2);
+  }
+  const [recipient, filename] = positional;
+  const path = join(MAILBOX_ROOT, recipient, filename);
+  if (!existsSync(path)) { console.error(`flo messages read: not found: ${path}`); process.exit(1); }
+  const raw = await readFile(path, 'utf8');
+  if (json) { console.log(JSON.stringify({ recipient, filename, content: raw })); return; }
+  console.log(raw);
+}
+
+async function archiveCommand(args) {
+  const [recipient, filename] = args.filter((a) => !a.startsWith('--'));
+  if (!recipient || !filename) {
+    console.error(`flo messages archive: usage: flo messages archive <recipient> <filename>`);
+    process.exit(2);
+  }
+  const path = join(MAILBOX_ROOT, recipient, filename);
+  if (!existsSync(path)) { console.error(`flo messages archive: not found: ${path}`); process.exit(1); }
+  await unlink(path);
+  console.log(`flo messages archive: removed ${filename}`);
+}
+
+export async function listAllMailboxes() {
+  const recipients = await listRecipients();
+  const out = [];
+  for (const r of recipients) {
+    out.push({ recipient: r, messages: await listMessages(r) });
+  }
+  return out;
+}

package/lib/migrate.js

@@ -0,0 +1,88 @@
+import { readFile, writeFile, copyFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export async function migrate(args) {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
+    console.log(`flo migrate — register flo in ~/.claude/mcp.json
+
+Adds (or updates) an mcpServers.flo entry pointing at the flo CLI mcp endpoint.
+Leaves any existing ruflo/claude-flow entries intact — flo coexists, it does
+not overwrite. Idempotent. Backs up first.
+
+Usage:
+  flo migrate [--mcp-path <path>] [--dry-run]
+
+Options:
+  --mcp-path <path>   Override default ~/.claude/mcp.json location.
+  --dry-run           Print the diff without writing.
+  -h, --help          Show this help.
+`);
+    return;
+  }
+
+  const mcpPath = parsed.mcpPath || join(homedir(), '.claude', 'mcp.json');
+  let existing = { mcpServers: {} };
+  let raw = '';
+  if (existsSync(mcpPath)) {
+    raw = await readFile(mcpPath, 'utf8');
+    try { existing = JSON.parse(raw); } catch (e) {
+      throw new Error(`failed to parse ${mcpPath}: ${e.message}`);
+    }
+    if (!existing.mcpServers) existing.mcpServers = {};
+  } else {
+    process.stderr.write(`flo migrate: no existing config at ${mcpPath}, creating fresh\n`);
+  }
+
+  const desired = {
+    command: 'node',
+    args: [resolveFloBinPath(), 'mcp', 'start'],
+    env: { FLO_MCP: '1' },
+  };
+
+  const before = JSON.stringify(existing.mcpServers.flo || null);
+  existing.mcpServers.flo = desired;
+  const after = JSON.stringify(existing.mcpServers.flo);
+
+  if (before === after) {
+    console.log(`flo migrate: already up to date (${mcpPath})`);
+    return;
+  }
+
+  const next = JSON.stringify(existing, null, 2) + '\n';
+
+  if (parsed.dryRun) {
+    console.log(`# flo migrate (DRY RUN)`);
+    console.log(`# would write to: ${mcpPath}`);
+    console.log(next);
+    return;
+  }
+
+  await mkdir(join(homedir(), '.claude'), { recursive: true });
+  if (raw) {
+    const backup = `${mcpPath}.flo-bak.${Date.now()}`;
+    await copyFile(mcpPath, backup);
+    process.stderr.write(`flo migrate: backed up to ${backup}\n`);
+  }
+  await writeFile(mcpPath, next, 'utf8');
+  console.log(`flo migrate: registered 'flo' MCP server at ${mcpPath}`);
+}
+
+function parseArgs(args) {
+  const out = { help: false, dryRun: false, mcpPath: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--mcp-path') out.mcpPath = args[++i];
+  }
+  return out;
+}
+
+function resolveFloBinPath() {
+  const fromEnv = process.env.FLO_BIN;
+  if (fromEnv) return fromEnv;
+  return new URL('../bin/flo.js', import.meta.url).pathname;
+}