@fuzeelogik/myflo 1.0.0-rc.4

package/lib/guidance-audit.js

@@ -0,0 +1,215 @@
+import { readdir, readFile, stat, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename, relative, sep } from 'node:path';
+
+const KINDS = ['skills', 'commands', 'agents'];
+
+export async function guidanceAudit(args) {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
+    console.log(`flo guidance audit — capability dedup report
+
+Usage:
+  flo guidance audit [--out <file>] [--json] [--scope user|project|all]
+
+Options:
+  --out <file>    Write markdown report to file (default: stdout).
+  --json          Output JSON instead of markdown.
+  --scope <s>     Restrict scope (user, project, all). Default: all.
+  --quiet         Suppress progress lines on stderr.
+  -h, --help      Show this help.
+`);
+    return;
+  }
+
+  const scopes = collectScopes(parsed.scope);
+  const records = [];
+  for (const scope of scopes) {
+    for (const kind of KINDS) {
+      const dir = join(scope.root, kind);
+      if (!existsSync(dir)) continue;
+      const found = await scanCapabilityDir(dir, kind, scope.label);
+      records.push(...found);
+    }
+  }
+
+  if (!parsed.quiet) {
+    process.stderr.write(`flo guidance audit: scanned ${records.length} capabilities across ${scopes.length} scope(s)\n`);
+  }
+
+  const report = analyze(records);
+
+  if (parsed.json) {
+    const out = JSON.stringify({ records, ...report }, null, 2);
+    if (parsed.out) await writeOut(parsed.out, out);
+    else console.log(out);
+    return;
+  }
+
+  const md = renderMarkdown(records, report);
+  if (parsed.out) await writeOut(parsed.out, md);
+  else console.log(md);
+}
+
+function parseArgs(args) {
+  const out = { scope: 'all', json: false, quiet: false, help: false, out: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '--quiet') out.quiet = true;
+    else if (a === '--scope') out.scope = args[++i];
+    else if (a === '--out') out.out = args[++i];
+  }
+  return out;
+}
+
+function collectScopes(scope) {
+  const scopes = [];
+  if (scope === 'all' || scope === 'user') {
+    scopes.push({ label: 'user', root: join(homedir(), '.claude') });
+  }
+  if (scope === 'all' || scope === 'project') {
+    scopes.push({ label: 'project', root: join(process.cwd(), '.claude') });
+  }
+  return scopes;
+}
+
+async function scanCapabilityDir(dir, kind, scope) {
+  const records = [];
+  const walk = async (current) => {
+    let entries;
+    try { entries = await readdir(current, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      const full = join(current, e.name);
+      if (e.isDirectory()) {
+        await walk(full);
+      } else if (e.isFile()) {
+        const ext = e.name.split('.').pop();
+        if (!['md', 'yaml', 'yml', 'json'].includes(ext)) continue;
+        records.push(await inspectFile(full, kind, scope, dir));
+      }
+    }
+  };
+  await walk(dir);
+  return records;
+}
+
+async function inspectFile(path, kind, scope, kindRoot) {
+  let content = '';
+  try { content = await readFile(path, 'utf8'); } catch {}
+  const fm = parseFrontmatter(content);
+  const name = fm.name || basename(path).replace(/\.(md|ya?ml|json)$/i, '');
+  return {
+    name,
+    kind,
+    scope,
+    path,
+    relPath: relative(kindRoot, path),
+    description: fm.description || '',
+    tags: Array.isArray(fm.tags) ? fm.tags : (typeof fm.tags === 'string' ? fm.tags.split(',').map(t => t.trim()) : []),
+    bytes: content.length,
+  };
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  const fm = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z_][\w-]*)\s*:\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    let val = kv[2].trim();
+    if (val.startsWith('[') && val.endsWith(']')) {
+      val = val.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    } else {
+      val = val.replace(/^["']|["']$/g, '');
+    }
+    fm[key] = val;
+  }
+  return fm;
+}
+
+function analyze(records) {
+  const byName = new Map();
+  for (const r of records) {
+    const key = `${r.kind}:${r.name}`;
+    if (!byName.has(key)) byName.set(key, []);
+    byName.get(key).push(r);
+  }
+  const duplicates = [];
+  for (const [key, list] of byName) {
+    if (list.length > 1) duplicates.push({ key, name: list[0].name, kind: list[0].kind, count: list.length, occurrences: list });
+  }
+  const missingDescription = records.filter(r => !r.description);
+  const scopeHistogram = {};
+  const kindHistogram = {};
+  for (const r of records) {
+    scopeHistogram[r.scope] = (scopeHistogram[r.scope] || 0) + 1;
+    const k = `${r.scope}:${r.kind}`;
+    kindHistogram[k] = (kindHistogram[k] || 0) + 1;
+  }
+  return { duplicates, missingDescription, scopeHistogram, kindHistogram, total: records.length };
+}
+
+function renderMarkdown(records, report) {
+  const lines = [];
+  lines.push(`# flo guidance audit`);
+  lines.push('');
+  lines.push(`Scanned **${report.total}** capabilities.`);
+  lines.push('');
+  lines.push(`## Scope distribution`);
+  lines.push('');
+  lines.push('| Scope | Count |');
+  lines.push('|---|---|');
+  for (const [scope, count] of Object.entries(report.scopeHistogram).sort()) {
+    lines.push(`| ${scope} | ${count} |`);
+  }
+  lines.push('');
+  lines.push(`## Kind × scope`);
+  lines.push('');
+  lines.push('| Scope:kind | Count |');
+  lines.push('|---|---|');
+  for (const [k, count] of Object.entries(report.kindHistogram).sort()) {
+    lines.push(`| ${k} | ${count} |`);
+  }
+  lines.push('');
+  lines.push(`## Duplicates (${report.duplicates.length})`);
+  lines.push('');
+  if (!report.duplicates.length) {
+    lines.push('_No duplicates detected._');
+  } else {
+    for (const dup of report.duplicates.sort((a, b) => b.count - a.count)) {
+      lines.push(`### \`${dup.kind}/${dup.name}\` (${dup.count} copies)`);
+      lines.push('');
+      for (const o of dup.occurrences) {
+        lines.push(`- \`${o.scope}\` — ${o.path}${o.description ? '  \n  > ' + o.description : ''}`);
+      }
+      lines.push('');
+    }
+  }
+  lines.push(`## Missing description (${report.missingDescription.length})`);
+  lines.push('');
+  if (!report.missingDescription.length) {
+    lines.push('_All capabilities have descriptions._');
+  } else {
+    for (const r of report.missingDescription.slice(0, 100)) {
+      lines.push(`- \`${r.scope}/${r.kind}/${r.name}\` — ${r.path}`);
+    }
+    if (report.missingDescription.length > 100) {
+      lines.push(`- _…and ${report.missingDescription.length - 100} more._`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+async function writeOut(path, content) {
+  const parent = path.split(sep).slice(0, -1).join(sep);
+  if (parent && !existsSync(parent)) await mkdir(parent, { recursive: true });
+  await writeFile(path, content, 'utf8');
+  process.stderr.write(`flo guidance audit: wrote ${path}\n`);
+}

package/lib/help.js

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export function printHelp() {
+  console.log(`flo — local-first developer workbench
+
+Usage:
+  flo <command> [options]
+
+Commands:
+  guidance audit              Scan ~/.claude/{skills,commands,agents}/ and project
+                              .claude/ for duplicate, missing-description, or
+                              orphan capabilities. Output: markdown report.
+  migrate                     Rewrite ~/.claude/mcp.json to register 'flo' as an
+                              MCP server. Idempotent. Backs up first.
+  sessions list               List Claude Code session checkpoints in
+                              .claude/checkpoints/ for the current project.
+  inbox watch <dir>           Watch a folder for drops. Markdown frontmatter routes
+                              to memory/SendMessage; .m4a/.wav/.mp3 transcribed
+                              locally (whisper/mlx-whisper). Sidecar .txt written
+                              next to each audio file. (Foreground; no launchd yet.)
+  inbox status                Show registered inbox handlers and recent activity.
+  transcribe <file>           Local audio transcription via whisper/mlx-whisper.
+                              Use --save for a sidecar .txt; --detect to check
+                              which tool is available.
+  doctor                      Quick health check: Node, git, .claude dir,
+                              checkpoints, MCP config.
+  help, -h, --help            Show this help.
+  version, -v, --version      Show flo version.
+
+Environment:
+  FLO_DEBUG=1                 Print stack traces on error.
+  FLO_HOME=<path>             Override ~/.flo (default).
+
+Docs: https://github.com/therealsiege/myflo
+`);
+}
+
+export function printVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+    console.log(`flo ${pkg.version}`);
+  } catch {
+    console.log('flo (unknown version)');
+  }
+}

package/lib/hook-cmd.js

@@ -0,0 +1,129 @@
+// `flo hook <event>` — Claude Code hook dispatcher.
+// Replaces .claude/helpers/hook-handler.cjs (and friends) with a single
+// canonical entrypoint. Each event takes whatever env vars Claude Code
+// supplies, does the corresponding flo work (memory store, task event,
+// activity log), and exits 0. Hooks are best-effort and never fail loudly
+// — a hook crashing should not break the user's Claude Code session.
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { storeEntry } from './memory-store.js';
+
+const FLO_HOME = process.env.FLO_HOME || join(homedir(), '.flo');
+const HOOK_LOG = join(FLO_HOME, 'logs', 'hooks.jsonl');
+
+const EVENTS = [
+  'pre-task', 'post-task', 'pre-edit', 'post-edit',
+  'pre-command', 'post-command', 'pre-bash', 'post-bash',
+  'session-start', 'session-end', 'session-restore',
+  'route', 'notify', 'pretrain', 'compact-manual', 'compact-auto',
+  'subagent-stop', 'stop',
+];
+
+export async function hookCommand(args) {
+  const [event = 'help', ...rest] = args;
+  if (event === 'help' || event === '--help' || event === '-h' || event === 'list') {
+    return printHelp();
+  }
+  // Hooks should NEVER fail the Claude Code session — wrap everything.
+  try {
+    await ensureLogDir();
+    await logEvent(event, rest);
+    if (event === 'post-task' || event === 'post-edit') {
+      await maybeRecordOutcome(event, rest);
+    }
+    if (event === 'route') {
+      // Print empty string — Claude Code's hook protocol expects stdout to be
+      // injected as user-facing context. Routing recommendations go to memory
+      // instead; the agent can call flo_memory_search if it wants them.
+      process.stdout.write('');
+    }
+    process.exit(0);
+  } catch (err) {
+    // Best-effort: log to stderr but exit 0 so we don't block Claude Code
+    process.stderr.write(`flo hook ${event}: ${err.message || err}\n`);
+    process.exit(0);
+  }
+}
+
+function printHelp() {
+  console.log(`flo hook — Claude Code hook dispatcher
+
+Usage:
+  flo hook <event> [args...]
+
+Events:
+  ${EVENTS.join(', ')}
+
+All events append a record to ~/.flo/logs/hooks.jsonl. Some events also write
+to flo memory (post-task / post-edit outcomes). Hooks are best-effort —
+a crash never fails the Claude Code session.
+
+Wire up by adding to .claude/settings.json hooks:
+  {
+    "hooks": {
+      "PreToolUse": [{
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": "node \${CLAUDE_PROJECT_DIR}/apps/cli/bin/flo.js hook pre-bash",
+          "timeout": 5000
+        }]
+      }]
+    }
+  }
+`);
+}
+
+async function ensureLogDir() {
+  const dir = join(FLO_HOME, 'logs');
+  if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+}
+
+async function logEvent(event, args) {
+  const record = {
+    event,
+    ts: new Date().toISOString(),
+    args,
+    env: collectEnv(),
+    pid: process.pid,
+  };
+  await appendFile(HOOK_LOG, JSON.stringify(record) + '\n', 'utf8');
+}
+
+// Pull the env vars Claude Code typically provides; ignore the rest
+function collectEnv() {
+  const wanted = [
+    'CLAUDE_PROJECT_DIR', 'CLAUDE_TOOL_NAME', 'CLAUDE_HOOK_EVENT',
+    'CLAUDE_SESSION_ID', 'CLAUDE_FILE_PATHS', 'CLAUDE_COMMAND',
+    'CLAUDE_NOTIFICATION', 'CLAUDE_MESSAGE',
+  ];
+  const out = {};
+  for (const k of wanted) if (process.env[k]) out[k] = process.env[k];
+  return out;
+}
+
+// If Claude Code provides task / edit context via env, mirror into memory so
+// flo's activity feed picks it up. Otherwise it's a quiet no-op.
+async function maybeRecordOutcome(event, args) {
+  const env = collectEnv();
+  const tool = env.CLAUDE_TOOL_NAME;
+  const files = env.CLAUDE_FILE_PATHS;
+  if (!tool && !files && !args.length) return;
+  const summary = [tool, files, args.join(' ')].filter(Boolean).join(' / ').slice(0, 200);
+  try {
+    await storeEntry({
+      namespace: 'hooks',
+      key: `${event}:${Date.now()}`,
+      value: summary || event,
+      tags: [event, tool || 'unknown'].filter(Boolean),
+      metadata: { ...env, event, args },
+    });
+  } catch {
+    // jsonl store fails silently; that's fine
+  }
+}
+
+export const _internal = { HOOK_LOG, EVENTS };

package/lib/inbox-install.js

@@ -0,0 +1,111 @@
+// macOS launchd plist generator for `flo inbox watch --once` loops.
+// Generates one launch agent per registered inbox slug.
+// No automatic launchctl load — prints the bootstrap command instead, so the
+// user keeps control. (Same pattern watchthis uses; less footgun.)
+
+import { mkdir, writeFile, unlink, readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { loadRegistry } from './inbox-registry.js';
+
+const LAUNCH_AGENTS_DIR = join(homedir(), 'Library', 'LaunchAgents');
+const LABEL_PREFIX = 'io.myflo.inbox';
+
+function plistFor({ label, dir, interval, floBin, logDir }) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${escapeXml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(process.execPath)}</string>
+    <string>${escapeXml(floBin)}</string>
+    <string>inbox</string>
+    <string>watch</string>
+    <string>${escapeXml(dir)}</string>
+    <string>--once</string>
+  </array>
+  <key>WorkingDirectory</key><string>${escapeXml(dirname(floBin))}</string>
+  <key>StartInterval</key><integer>${Number(interval) || 30}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>${escapeXml(join(logDir, label + '.out.log'))}</string>
+  <key>StandardErrorPath</key><string>${escapeXml(join(logDir, label + '.err.log'))}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+    <key>HOME</key><string>${escapeXml(homedir())}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function labelFor(slug) {
+  return `${LABEL_PREFIX}.${slug}`;
+}
+
+function plistPathFor(slug) {
+  return join(LAUNCH_AGENTS_DIR, `${labelFor(slug)}.plist`);
+}
+
+async function resolveFloBin() {
+  if (process.env.FLO_BIN) return process.env.FLO_BIN;
+  return new URL('../bin/flo.js', import.meta.url).pathname;
+}
+
+export async function installLaunchAgent({ slug, interval = 30 }) {
+  if (process.platform !== 'darwin') {
+    throw new Error(`launchd install is macOS-only (current: ${process.platform})`);
+  }
+  const reg = await loadRegistry();
+  const entry = reg.inboxes.find((i) => i.slug === slug);
+  if (!entry) {
+    throw new Error(`no inbox registered with slug '${slug}'. Run 'flo inbox add <dir>' first.`);
+  }
+  await mkdir(LAUNCH_AGENTS_DIR, { recursive: true });
+  const logDir = join(homedir(), '.flo', 'logs');
+  await mkdir(logDir, { recursive: true });
+  const floBin = await resolveFloBin();
+  const label = labelFor(slug);
+  const plistPath = plistPathFor(slug);
+  const content = plistFor({ label, dir: entry.dir, interval, floBin, logDir });
+  await writeFile(plistPath, content, 'utf8');
+  return { label, plistPath, dir: entry.dir, interval };
+}
+
+export async function uninstallLaunchAgent({ slug }) {
+  if (process.platform !== 'darwin') {
+    throw new Error(`launchd uninstall is macOS-only (current: ${process.platform})`);
+  }
+  const plistPath = plistPathFor(slug);
+  if (!existsSync(plistPath)) return { removed: false, plistPath };
+  await unlink(plistPath);
+  return { removed: true, plistPath };
+}
+
+export async function listInstalledAgents() {
+  if (!existsSync(LAUNCH_AGENTS_DIR)) return [];
+  const entries = await readdir(LAUNCH_AGENTS_DIR);
+  const out = [];
+  for (const name of entries) {
+    if (!name.startsWith(`${LABEL_PREFIX}.`) || !name.endsWith('.plist')) continue;
+    const slug = name.slice(`${LABEL_PREFIX}.`.length, -'.plist'.length);
+    out.push({ slug, plistPath: join(LAUNCH_AGENTS_DIR, name) });
+  }
+  return out;
+}
+
+// Exported for tests / introspection
+export const _internal = { plistFor, labelFor, plistPathFor, LAUNCH_AGENTS_DIR };

package/lib/inbox-registry.js

@@ -0,0 +1,122 @@
+// ~/.flo/inboxes.json — small registry of named inboxes that flo manages.
+// Used by `flo inbox list`, `/inbox` web panel, and the launchd installer.
+
+import { mkdir, readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, basename } from 'node:path';
+
+const FLO_HOME = process.env.FLO_HOME || join(homedir(), '.flo');
+const REGISTRY_PATH = join(FLO_HOME, 'inboxes.json');
+
+function slugify(input) {
+  return String(input)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'inbox';
+}
+
+async function ensureHome() {
+  if (!existsSync(FLO_HOME)) await mkdir(FLO_HOME, { recursive: true });
+}
+
+export async function loadRegistry() {
+  await ensureHome();
+  if (!existsSync(REGISTRY_PATH)) return { version: 1, inboxes: [] };
+  try {
+    const raw = await readFile(REGISTRY_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.inboxes)) {
+      return { version: 1, inboxes: [] };
+    }
+    return parsed;
+  } catch {
+    return { version: 1, inboxes: [] };
+  }
+}
+
+export async function saveRegistry(reg) {
+  await ensureHome();
+  await writeFile(REGISTRY_PATH, JSON.stringify(reg, null, 2) + '\n', 'utf8');
+}
+
+export async function addInbox({ dir, slug, handlerHints }) {
+  const reg = await loadRegistry();
+  const resolved = resolve(dir.replace(/^~/, homedir()));
+  const finalSlug = slug ? slugify(slug) : slugify(basename(resolved));
+  // Ensure slug uniqueness
+  const existingByDir = reg.inboxes.find((i) => i.dir === resolved);
+  if (existingByDir) {
+    // Idempotent: return existing entry
+    return existingByDir;
+  }
+  let uniqueSlug = finalSlug;
+  let n = 1;
+  while (reg.inboxes.find((i) => i.slug === uniqueSlug)) {
+    uniqueSlug = `${finalSlug}-${++n}`;
+  }
+  const entry = {
+    slug: uniqueSlug,
+    dir: resolved,
+    createdAt: new Date().toISOString(),
+    handlerHints: Array.isArray(handlerHints) ? handlerHints : [],
+  };
+  reg.inboxes.push(entry);
+  await saveRegistry(reg);
+  return entry;
+}
+
+export async function removeInbox(slug) {
+  const reg = await loadRegistry();
+  const before = reg.inboxes.length;
+  reg.inboxes = reg.inboxes.filter((i) => i.slug !== slug);
+  const removed = before - reg.inboxes.length;
+  await saveRegistry(reg);
+  return removed > 0;
+}
+
+export async function listInboxes() {
+  const reg = await loadRegistry();
+  const enriched = [];
+  for (const i of reg.inboxes) {
+    enriched.push({ ...i, ...(await statInbox(i.dir)) });
+  }
+  return enriched;
+}
+
+async function statInbox(dir) {
+  const out = { exists: false, pending: 0, processed: 0, failed: 0, lastActivity: null };
+  if (!existsSync(dir)) return out;
+  out.exists = true;
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isFile()) continue;
+      if (e.name.startsWith('.')) continue;
+      if (e.name === 'inbox.log') continue;
+      out.pending++;
+    }
+  } catch {}
+  for (const subdir of ['.processed', '.failed']) {
+    const p = join(dir, subdir);
+    if (existsSync(p)) {
+      try {
+        const list = await readdir(p);
+        if (subdir === '.processed') out.processed = list.length;
+        else out.failed = list.length;
+      } catch {}
+    }
+  }
+  const logPath = join(dir, 'inbox.log');
+  if (existsSync(logPath)) {
+    try {
+      const st = await stat(logPath);
+      out.lastActivity = st.mtimeMs;
+    } catch {}
+  }
+  return out;
+}
+
+export const REGISTRY = { FLO_HOME, REGISTRY_PATH };
+export { slugify };