@fuzeelogik/myflo 1.0.0-rc.4

package/lib/completions.js

@@ -0,0 +1,120 @@
+// `flo completions <shell>` — emit autocomplete scripts for bash/zsh/fish.
+// Static command list; users sourcing the output get tab completion.
+
+const TOP_COMMANDS = [
+  'help', 'version', 'guidance', 'migrate', 'sessions', 'inbox', 'doctor',
+  'mcp', 'transcribe', 'swarm', 'memory', 'messages', 'transcripts',
+  'tasks', 'notes', 'setup', 'export', 'import', 'log', 'completions',
+  'session', 'activity', 'edit',
+];
+
+const SUBCOMMANDS = {
+  guidance: ['audit'],
+  sessions: ['list'],
+  inbox: ['watch', 'status', 'add', 'list', 'remove', 'install', 'uninstall', 'help'],
+  mcp: ['start'],
+  swarm: ['status'],
+  memory: ['store', 'search', 'list', 'get', 'delete', 'namespaces'],
+  messages: ['list', 'read', 'archive', 'help'],
+  transcripts: ['list'],
+  tasks: ['create', 'list', 'update', 'complete', 'delete', 'get', 'counts'],
+  notes: ['list', 'search'],
+  session: ['terminal-add', 'terminal-list', 'terminal-remove', 'terminal-restore'],
+  activity: ['list'],
+  completions: ['bash', 'zsh', 'fish'],
+};
+
+export async function completionsCommand(args) {
+  const [shell] = args;
+  if (!shell || shell === '--help' || shell === '-h') return printHelp();
+  if (shell === 'bash') return printBash();
+  if (shell === 'zsh') return printZsh();
+  if (shell === 'fish') return printFish();
+  console.error(`flo completions: unknown shell '${shell}'. Try: bash, zsh, fish`);
+  process.exit(2);
+}
+
+function printHelp() {
+  console.log(`flo completions — emit shell autocomplete scripts
+
+Usage:
+  flo completions bash  >> ~/.bashrc                # or sourceable file
+  flo completions zsh   >> ~/.zshrc                 # or to a fpath dir
+  flo completions fish  > ~/.config/fish/completions/flo.fish
+
+Each output is a complete, sourceable shell snippet. No runtime dependencies
+beyond a working flo binary (uses the static command list, not introspection).
+`);
+}
+
+function topWords() { return TOP_COMMANDS.sort().join(' '); }
+
+function subcaseBash() {
+  return Object.entries(SUBCOMMANDS)
+    .map(([cmd, subs]) => `        ${cmd}) COMPREPLY=($(compgen -W "${subs.join(' ')}" -- "$cur")); return 0;;`)
+    .join('\n');
+}
+
+function printBash() {
+  console.log(`# flo bash completion. Source from .bashrc or save to /etc/bash_completion.d/flo
+_flo() {
+  local cur prev cmd
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  cmd="\${COMP_WORDS[1]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=($(compgen -W "${topWords()}" -- "$cur"))
+    return 0
+  fi
+  if [ "$COMP_CWORD" -eq 2 ]; then
+    case "$cmd" in
+${subcaseBash()}
+    esac
+  fi
+  return 0
+}
+complete -F _flo flo
+`);
+}
+
+function subcaseZsh() {
+  return Object.entries(SUBCOMMANDS)
+    .map(([cmd, subs]) => `      ${cmd}) _values 'subcommand' ${subs.map((s) => `'${s}'`).join(' ')} ;;`)
+    .join('\n');
+}
+
+function printZsh() {
+  console.log(`#compdef flo
+# flo zsh completion. Save to a directory in $fpath, e.g. ~/.zsh/completions/_flo
+_flo() {
+  local -a top
+  top=(${TOP_COMMANDS.map((c) => `'${c}'`).join(' ')})
+  if (( CURRENT == 2 )); then
+    _values 'flo command' \${top[@]}
+    return
+  fi
+  if (( CURRENT == 3 )); then
+    case "\${words[2]}" in
+${subcaseZsh()}
+    esac
+  fi
+}
+_flo "$@"
+`);
+}
+
+function printFish() {
+  // fish: emit one completion line per subcommand
+  const lines = [];
+  lines.push(`# flo fish completion. Save to ~/.config/fish/completions/flo.fish`);
+  lines.push(`complete -c flo -f`);
+  for (const cmd of TOP_COMMANDS) {
+    lines.push(`complete -c flo -n '__fish_use_subcommand' -a '${cmd}'`);
+  }
+  for (const [cmd, subs] of Object.entries(SUBCOMMANDS)) {
+    for (const sub of subs) {
+      lines.push(`complete -c flo -n "__fish_seen_subcommand_from ${cmd}" -a '${sub}'`);
+    }
+  }
+  console.log(lines.join('\n'));
+}

package/lib/doctor.js

@@ -0,0 +1,101 @@
+import { existsSync } from 'node:fs';
+import { stat, readFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CHECKS = [
+  { name: 'node>=20', run: checkNode },
+  { name: 'git', run: checkGit },
+  { name: '.claude/ project', run: checkProjectClaude },
+  { name: '.claude/checkpoints', run: checkCheckpoints },
+  { name: '~/.claude/mcp.json', run: checkMcp },
+  { name: 'flo bin resolvable', run: checkFloBin },
+];
+
+export async function doctor(args) {
+  if (args.includes('-h') || args.includes('--help')) {
+    console.log(`flo doctor — quick health check
+
+Usage:
+  flo doctor [--json]
+`);
+    return;
+  }
+  const json = args.includes('--json');
+  const results = [];
+  for (const c of CHECKS) {
+    try {
+      const r = await c.run();
+      results.push({ name: c.name, ok: r.ok, message: r.message });
+    } catch (err) {
+      results.push({ name: c.name, ok: false, message: err.message });
+    }
+  }
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  const longest = Math.max(...results.map(r => r.name.length));
+  for (const r of results) {
+    const pad = r.name.padEnd(longest);
+    const status = r.ok ? 'PASS' : 'FAIL';
+    console.log(`  ${pad}  ${status}  ${r.message}`);
+  }
+  const failed = results.filter(r => !r.ok).length;
+  console.log(`\nflo doctor: ${results.length - failed}/${results.length} checks passed.`);
+  if (failed) process.exit(1);
+}
+
+async function checkNode() {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= 20) return { ok: true, message: process.versions.node };
+  return { ok: false, message: `Node ${process.versions.node} (need >=20)` };
+}
+
+async function checkGit() {
+  try {
+    const v = execFileSync('git', ['--version'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    return { ok: true, message: v };
+  } catch {
+    return { ok: false, message: 'git not on PATH' };
+  }
+}
+
+async function checkProjectClaude() {
+  const p = join(process.cwd(), '.claude');
+  if (existsSync(p)) {
+    const st = await stat(p);
+    if (st.isDirectory()) return { ok: true, message: p };
+  }
+  return { ok: false, message: `${p} not found (not in a Claude Code project?)` };
+}
+
+async function checkCheckpoints() {
+  const p = join(process.cwd(), '.claude', 'checkpoints');
+  if (!existsSync(p)) return { ok: false, message: 'no checkpoints dir (sessions not yet captured)' };
+  return { ok: true, message: p };
+}
+
+async function checkMcp() {
+  const p = join(homedir(), '.claude', 'mcp.json');
+  if (!existsSync(p)) return { ok: false, message: `${p} missing (run 'flo migrate')` };
+  try {
+    const raw = await readFile(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    const servers = Object.keys(parsed.mcpServers || {});
+    const hasFlo = servers.includes('flo');
+    return {
+      ok: true,
+      message: `servers=[${servers.join(',')}]${hasFlo ? '' : " (run 'flo migrate' to register flo)"}`,
+    };
+  } catch (err) {
+    return { ok: false, message: `parse error: ${err.message}` };
+  }
+}
+
+async function checkFloBin() {
+  const p = new URL('../bin/flo.js', import.meta.url).pathname;
+  if (existsSync(p)) return { ok: true, message: p };
+  return { ok: false, message: `expected ${p}` };
+}

package/lib/edit-cmd.js

@@ -0,0 +1,136 @@
+// `flo edit` — open memory entries, notes, or tasks in $EDITOR.
+// Writes the content to a tmpfile, invokes the editor, then applies the result.
+// Memory/note edits create a new entry (the old one stays in history via the
+// append-only log + tombstone pattern); task edits use updateTask.
+
+import { mkdtemp, writeFile, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { getEntry, storeEntry, deleteEntry } from './memory-store.js';
+import { getTask, updateTask } from './tasks-store.js';
+
+export async function editCommand(args) {
+  const [kind = 'help', ...rest] = args;
+  if (kind === 'help' || kind === '--help' || kind === '-h') return printHelp();
+  if (kind === 'memory' || kind === 'note') return editMemory(kind, rest);
+  if (kind === 'task') return editTask(rest);
+  console.error(`flo edit: unknown kind '${kind}'. Try: memory, note, task`);
+  process.exit(2);
+}
+
+function printHelp() {
+  console.log(`flo edit — open in \$EDITOR (defaults to vim)
+
+Usage:
+  flo edit memory <id>              # edit memory entry by id
+  flo edit memory --key <key> [--namespace <ns>]
+  flo edit note <id>                # alias of: flo edit memory <id> (in 'notes' ns)
+  flo edit task <id>                # edit a task's subject + description
+
+Memory/note edits create a new entry (the old one is tombstoned but still in
+the history log). Task edits update the existing task event log.
+
+\$EDITOR is honored; falls back to vim, then nano.
+`);
+}
+
+function pickEditor() {
+  if (process.env.EDITOR) return process.env.EDITOR;
+  if (process.env.VISUAL) return process.env.VISUAL;
+  // Reasonable fallbacks
+  return 'vim';
+}
+
+async function openInEditor(initialContent) {
+  const dir = await mkdtemp(join(tmpdir(), 'flo-edit-'));
+  const path = join(dir, 'flo-edit.md');
+  await writeFile(path, initialContent, 'utf8');
+  const editor = pickEditor();
+  // Parse simple "editor +line" / "editor --wait" forms by splitting on whitespace.
+  // Shell expansion isn't supported (we pass an arg array to spawn, never a shell string).
+  const parts = editor.split(/\s+/);
+  await new Promise((resolve, reject) => {
+    const proc = spawn(parts[0], [...parts.slice(1), path], { stdio: 'inherit' });
+    proc.on('error', reject);
+    proc.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`editor exited ${code}`)));
+  });
+  const updated = await readFile(path, 'utf8');
+  return { path, original: initialContent, updated };
+}
+
+function parseFlags(args) {
+  const out = { positional: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--namespace') out.namespace = args[++i];
+    else if (a === '--key') out.key = args[++i];
+    else if (!a.startsWith('--')) out.positional.push(a);
+  }
+  return out;
+}
+
+async function editMemory(kind, args) {
+  const opts = parseFlags(args);
+  let namespace = opts.namespace || (kind === 'note' ? 'notes' : 'default');
+  const id = opts.positional[0];
+  let entry;
+  if (id) {
+    entry = await getEntry({ namespace, id });
+  } else if (opts.key) {
+    entry = await getEntry({ namespace, key: opts.key });
+  } else {
+    console.error(`flo edit ${kind}: need <id> or --key`);
+    process.exit(2);
+  }
+  if (!entry) {
+    console.error(`flo edit ${kind}: not found in namespace '${namespace}'`);
+    process.exit(1);
+  }
+  const { updated } = await openInEditor(entry.value);
+  if (updated.trim() === entry.value.trim()) {
+    console.log(`flo edit ${kind}: no changes`);
+    return;
+  }
+  const next = await storeEntry({
+    namespace: entry.namespace,
+    key: entry.key,
+    value: updated,
+    tags: entry.tags,
+    metadata: { ...entry.metadata, editedFrom: entry.id, editedAt: new Date().toISOString() },
+  });
+  await deleteEntry({ namespace: entry.namespace, id: entry.id });
+  console.log(`flo edit ${kind}: ${entry.id} → ${next.id} (${updated.length} chars)`);
+}
+
+async function editTask(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(`flo edit task: missing <id>`);
+    process.exit(2);
+  }
+  const task = await getTask(id);
+  if (!task) { console.error(`flo edit task: no task ${id}`); process.exit(1); }
+  const body = `# subject (first line) and optional description (below)
+${task.subject}
+${task.description ? '\n' + task.description : ''}
+`;
+  const { updated } = await openInEditor(body);
+  const lines = updated.split('\n');
+  // Skip the comment line if user kept it
+  const firstReal = lines.findIndex((l) => l && !l.startsWith('#'));
+  const newSubject = (firstReal >= 0 ? lines[firstReal] : '').trim();
+  const newDesc = firstReal >= 0
+    ? lines.slice(firstReal + 1).join('\n').trim() || null
+    : null;
+  if (!newSubject) {
+    console.error(`flo edit task: empty subject — refused`);
+    process.exit(1);
+  }
+  if (newSubject === task.subject && (newDesc || '') === (task.description || '')) {
+    console.log(`flo edit task: no changes`);
+    return;
+  }
+  const next = await updateTask({ id, subject: newSubject, description: newDesc });
+  console.log(`flo edit task: ${next.id} updated`);
+}

package/lib/export.js

@@ -0,0 +1,182 @@
+// `flo export` / `flo import` — portable ~/.flo backup.
+// Uses Node's stream APIs + a tiny tar-like JSON-bundle format so we don't
+// pull in any tar library. Easy to unpack from any language.
+//
+// Bundle format (.flo.json.gz):
+//   gzipped JSON: { manifest: {version, exportedAt, source}, files: [
+//     { path: "memory/notes.jsonl", content: "<base64>", size, mtime },
+//     ...
+//   ]}
+
+import { createGzip, createGunzip } from 'node:zlib';
+import { readFile, writeFile, mkdir, stat, readdir } from 'node:fs/promises';
+import { existsSync, createReadStream, createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { homedir } from 'node:os';
+import { join, resolve, dirname, sep, normalize } from 'node:path';
+import { Readable } from 'node:stream';
+
+const FLO_HOME = process.env.FLO_HOME || join(homedir(), '.flo');
+const BUNDLE_VERSION = 1;
+
+export async function exportCommand(args) {
+  const opts = parseFlags(args);
+  if (opts.help) return printExportHelp();
+  const outPath = opts.out || `flo-export-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}.flo.json.gz`;
+
+  if (!existsSync(FLO_HOME)) {
+    console.error(`flo export: no ~/.flo directory at ${FLO_HOME}`);
+    process.exit(1);
+  }
+
+  const files = await collectFiles(FLO_HOME, '');
+  const bundle = {
+    manifest: {
+      version: BUNDLE_VERSION,
+      exportedAt: new Date().toISOString(),
+      source: FLO_HOME,
+      fileCount: files.length,
+      totalBytes: files.reduce((s, f) => s + f.size, 0),
+    },
+    files,
+  };
+
+  const json = JSON.stringify(bundle);
+  await pipeline(
+    Readable.from(json),
+    createGzip({ level: 9 }),
+    createWriteStream(resolve(outPath)),
+  );
+  const outStat = await stat(resolve(outPath));
+  console.log(`flo export: wrote ${outPath}`);
+  console.log(`  ${files.length} files, ${bundle.manifest.totalBytes} bytes uncompressed, ${outStat.size} bytes compressed`);
+}
+
+export async function importCommand(args) {
+  const opts = parseFlags(args);
+  if (opts.help) return printImportHelp();
+  const inPath = opts.positional[0];
+  if (!inPath) {
+    console.error(`flo import: missing <bundle>`);
+    console.error(`Usage: flo import <bundle.flo.json.gz> [--target <dir>] [--force]`);
+    process.exit(2);
+  }
+  if (!existsSync(inPath)) {
+    console.error(`flo import: file not found: ${inPath}`);
+    process.exit(1);
+  }
+  const target = resolve((opts.target || FLO_HOME).replace(/^~/, homedir()));
+
+  // Stream-decode the gzipped JSON
+  const chunks = [];
+  await pipeline(
+    createReadStream(inPath),
+    createGunzip(),
+    async function* sink(source) {
+      for await (const chunk of source) chunks.push(Buffer.from(chunk));
+    },
+  );
+  const text = Buffer.concat(chunks).toString('utf8');
+  let bundle;
+  try { bundle = JSON.parse(text); } catch (err) {
+    console.error(`flo import: bundle is not valid JSON — ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!bundle?.manifest?.version) {
+    console.error(`flo import: invalid bundle (no manifest)`);
+    process.exit(1);
+  }
+  if (bundle.manifest.version > BUNDLE_VERSION) {
+    console.error(`flo import: bundle version ${bundle.manifest.version} exceeds supported ${BUNDLE_VERSION}`);
+    process.exit(1);
+  }
+
+  console.log(`flo import: ${bundle.files.length} files from bundle ${bundle.manifest.exportedAt}`);
+  if (opts.dryRun) {
+    for (const f of bundle.files.slice(0, 10)) console.log(`  would write: ${f.path}`);
+    if (bundle.files.length > 10) console.log(`  …and ${bundle.files.length - 10} more`);
+    return;
+  }
+
+  if (existsSync(target) && !opts.force) {
+    const existing = (await readdir(target)).filter((n) => !n.startsWith('.')).length;
+    if (existing > 0) {
+      console.error(`flo import: target ${target} is non-empty. Use --force to overwrite.`);
+      process.exit(1);
+    }
+  }
+  await mkdir(target, { recursive: true });
+
+  for (const f of bundle.files) {
+    // Path safety: must be a relative path inside target, no traversal
+    const rel = normalize(f.path);
+    if (rel.startsWith('..') || rel.startsWith(sep) || rel.includes('\0')) {
+      console.error(`flo import: refusing unsafe path '${f.path}' — skipped`);
+      continue;
+    }
+    const fullPath = join(target, rel);
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, Buffer.from(f.content, 'base64'));
+  }
+  console.log(`flo import: extracted ${bundle.files.length} files to ${target}`);
+}
+
+async function collectFiles(root, relPrefix) {
+  const out = [];
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const e of entries) {
+    const full = join(root, e.name);
+    const rel = relPrefix ? `${relPrefix}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      out.push(...await collectFiles(full, rel));
+    } else if (e.isFile()) {
+      const st = await stat(full);
+      const buf = await readFile(full);
+      out.push({
+        path: rel,
+        size: st.size,
+        mtime: st.mtimeMs,
+        content: buf.toString('base64'),
+      });
+    }
+  }
+  return out;
+}
+
+function printExportHelp() {
+  console.log(`flo export — bundle ~/.flo/ into a portable .flo.json.gz file
+
+Usage:
+  flo export [--out <path>]
+
+Default output filename: flo-export-<timestamp>.flo.json.gz
+Format: gzipped JSON {manifest, files[]} with base64 content. No native deps,
+portable across platforms.
+`);
+}
+
+function printImportHelp() {
+  console.log(`flo import — restore a flo export bundle
+
+Usage:
+  flo import <bundle.flo.json.gz> [--target <dir>] [--force] [--dry-run]
+
+By default extracts to ~/.flo. Refuses to overwrite a non-empty target unless
+--force. Path traversal in bundle entries is blocked.
+`);
+}
+
+function parseFlags(args) {
+  const out = { positional: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--out') out.out = args[++i];
+    else if (a === '--target') out.target = args[++i];
+    else if (a === '--force') out.force = true;
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (!a.startsWith('--')) out.positional.push(a);
+  }
+  return out;
+}