noggin-cli 0.1.3 → 0.4.2

package/noggin.mjs

@@ -1,45 +1,58 @@
 #!/usr/bin/env node
-// Noggin CLI — thin wrapper over noggin-api.mjs.
+// Noggin CLI — thin wrapper over the engine.
 //
 // Responsibilities:
 //   1. Parse argv into { verb, positional, flags }.
-//   2. Resolve the noggin file (--file / $NOGGIN_FILE / ~/.noggin.yaml).
-//   3. Translate flags into the verb's typed options object.
-//   4. Invoke the API; catch NogginError; format output.
+//   2. Resolve a noggin location (--noggin / $NOGGIN / default).
+//   3. Translate flags into verb option objects.
+//   4. Dispatch to `verbs.X(noggin, opts)` from the engine.
+//   5. Format the result for a terminal.
 //
-// All noggin logic lives in noggin-api.mjs. This file owns nothing about
-// the data model — only how to interpret argv and how to render results
-// for a terminal.
+// All noggin logic lives in the engine. This file owns nothing about
+// the data model — only argv interpretation and terminal rendering.
+//
+// Embedding: I/O and noggin construction are injected. `runCommand(argv,
+// { io, openNoggin, defaultLocationLabel })` returns a Promise<exitCode>
+// and never touches `process` directly, so the same dispatcher powers
+// the shebang entry below and the in-browser playground on the docs site.
+//
+// The Node file backend is imported lazily so the browser bundle can
+// avoid pulling in `node:fs`/`node:os`/`node:path`.
 
 import {
-  apiPush, apiAdd, apiMove, apiGoto, apiDone, apiPop, apiEdit,
-  apiShow, apiNote, apiDelete, apiWhere,
-  resolveFile, DEFAULT_FILE, NogginError,
+  NogginError,
+  factories,
   formatSuccess, formatError,
+  verbs,
 } from './noggin-api.mjs';
 
 // ── Argument parsing ─────────────────────────────────────────────────────────
 
-const VALUE_FLAGS = new Set(['file', 'title', 'before', 'after', 'into']);
+const VALUE_FLAGS = new Set(['noggin', 'title', 'before', 'after', 'into']);
 const OPTIONAL_VALUE_FLAGS = new Set(['goto']);
-const BOOL_FLAGS = new Set(['json', 'with-json', 'help', 'no-children', 'with-notes', 'done', 'open', 'recursive', 'with-siblings', 'with-descendants', 'with-all', 'force', 'close-all']);
-
-// Mutable handle so fail() can include the verb / file / --json state
-// regardless of where in the dispatch lifecycle the error fires.
-const exitContext = { verb: null, file: null, json: false };
+const BOOL_FLAGS = new Set([
+  'json', 'with-json', 'help', 'no-children', 'with-notes', 'done', 'open',
+  'recursive', 'with-siblings', 'with-descendants', 'with-all', 'force',
+  'close-all',
+]);
+
+// Internal sentinel: fail() throws this so runCommand() can convert it
+// into an exit code without unwinding into the embedder's stack.
+class ExitSignal extends Error {
+  constructor(code) { super(`exit:${code}`); this.code = code; this.name = 'ExitSignal'; }
+}
 
-function fail(msg, code = 2, errCode = 'noggin-error') {
-  if (exitContext.json) {
+function fail(ctx, msg, code = 2, errCode = 'noggin-error') {
+  if (ctx.json) {
     const envelope = formatError({
-      verb: exitContext.verb,
-      file: exitContext.file,
+      verb: ctx.verb,
       error: new NogginError(msg, { code: errCode, exitCode: code }),
     });
-    process.stderr.write(JSON.stringify(envelope, null, 2) + '\n');
+    ctx.io.stderr(JSON.stringify(envelope, null, 2) + '\n');
   } else {
-    process.stderr.write(`noggin: ${msg}\n`);
+    ctx.io.stderr(`noggin: ${msg}\n`);
   }
-  process.exit(code);
+  throw new ExitSignal(code);
 }
 
 function looksLikePath(value) {
@@ -47,9 +60,6 @@ function looksLikePath(value) {
   if (text === '.' || text === '..' || text === '-' || text === '+') return true;
   if (text.startsWith('./') || text.startsWith('../')) return true;
   if (text.startsWith('-/') || text.startsWith('+/')) return true;
-  // Position sequences. Absolute starts with `/`; bare `1/2/3` is relative
-  // (short for `./1/2/3`). looksLikePath only decides "is this an argument
-  // that looks like a path?" — the resolver decides what it means.
   if (/^\/?\d+(?:\/\d+)*$/.test(text)) return true;
   return false;
 }
@@ -60,7 +70,7 @@ function parseFlagToken(token) {
   return { key: token.slice(2, eq), value: token.slice(eq + 1), hasInlineValue: true };
 }
 
-function parseArgs(argv) {
+function parseArgs(ctx, argv) {
   const positional = [];
   const flags = {};
   for (let i = 0; i < argv.length; i++) {
@@ -83,13 +93,13 @@ function parseArgs(argv) {
       if (VALUE_FLAGS.has(key)) {
         const val = hasInlineValue ? value : argv[i + 1];
         if (val === undefined || val.startsWith('--')) {
-          fail(`flag --${key} requires a value`);
+          fail(ctx, `flag --${key} requires a value`);
         }
         flags[key] = val;
         if (!hasInlineValue) i++;
         continue;
       }
-      fail(`unknown flag: --${key}`);
+      fail(ctx, `unknown flag: --${key}`);
     } else {
       positional.push(a);
     }
@@ -97,7 +107,7 @@ function parseArgs(argv) {
   return { positional, flags };
 }
 
-function splitCommand(argv) {
+function splitCommand(ctx, argv) {
   const leading = [];
   let i = 0;
   while (i < argv.length && (argv[i].startsWith('--') || argv[i] === '-h')) {
@@ -109,7 +119,7 @@ function splitCommand(argv) {
       if (parsedFlag?.hasInlineValue) {
         i++;
       } else if (argv[i + 1] === undefined || argv[i + 1].startsWith('--')) {
-        fail(`flag --${key} requires a value`);
+        fail(ctx, `flag --${key} requires a value`);
       } else {
         leading.push(argv[i + 1]);
         i += 2;
@@ -130,19 +140,6 @@ function splitCommand(argv) {
 
 // ── Output formatting (terminal-only helpers) ────────────────────────────────
 
-/**
- * Format one row from an ItemView. Layout:
- *
- *   [indent]<path> (📍)(✅) title (✏️)
- *
- * The absolute path replaces the bracket-position notation so spine
- * ancestors (which only show one item per depth, with trimmed siblings)
- * still self-describe — `/1/3` reads as "third child of root 1" without
- * needing the surrounding peers for context.
- *
- * - 📍 (active) and ✅ (done) sit between the path and the title.
- * - ✏️ (has notes) is appended after the title.
- */
 function formatItemLine(item, activeKey, indent) {
   const leading = [];
   if (item.key === activeKey) leading.push('📍');
@@ -152,20 +149,12 @@ function formatItemLine(item, activeKey, indent) {
   return `${indent}${item.path ?? '?'} ${prefix}${item.title}${trailing}`;
 }
 
-/**
- * Render a CurrentTreeView as the human "current tree" view. The view is
- * a recursive tree of nodes — each node has an optional `children` slot
- * that's either `null` (a leaf of this view) or an array of more nodes.
- * Walk it directly: print the node, recurse into children if present,
- * append note bodies when we hit the target.
- */
-function printView(view, opts = {}) {
+function printView(ctx, view, opts = {}) {
   if (!view || !Array.isArray(view.items) || view.items.length === 0) {
-    process.stdout.write('(no item)\n');
+    ctx.io.stdout('(no item)\n');
     return;
   }
   const lines = [];
-
   function walk(node, depth) {
     const indent = '  '.repeat(depth);
     lines.push(formatItemLine(node, view.activeKey, indent));
@@ -181,122 +170,116 @@ function printView(view, opts = {}) {
       }
     }
   }
-
   for (const root of view.items) walk(root, 0);
-  process.stdout.write(lines.join('\n') + '\n');
+  ctx.io.stdout(lines.join('\n') + '\n');
 }
 
-function printJson(envelope) {
-  process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+function printJson(ctx, envelope) {
+  ctx.io.stdout(JSON.stringify(envelope, null, 2) + '\n');
 }
 
-function emitOutput(flags, human, data) {
+function emitOutput(ctx, flags, human, data) {
   if (flags.json) {
-    printJson(formatSuccess({ verb: exitContext.verb, file: exitContext.file, data }));
+    printJson(ctx, formatSuccess({ verb: ctx.verb, data }));
     return;
   }
   human();
   if (flags['with-json']) {
-    process.stdout.write('\n');
-    printJson(formatSuccess({ verb: exitContext.verb, file: exitContext.file, data }));
+    ctx.io.stdout('\n');
+    printJson(ctx, formatSuccess({ verb: ctx.verb, data }));
   }
 }
 
-/** Render a verb's CurrentTreeView in both human and JSON modes. */
-function emitView(view, flags, opts = {}) {
+function emitView(ctx, view, flags, opts = {}) {
   if (view === null || view === undefined) {
-    emitOutput(flags, () => process.stdout.write('(no item)\n'), view ?? null);
+    emitOutput(ctx, flags, () => ctx.io.stdout('(no item)\n'), view ?? null);
     return;
   }
   emitOutput(
+    ctx,
     flags,
-    () => printView(view, { includeNotes: Boolean(opts.includeNotes) }),
+    () => printView(ctx, view, { includeNotes: Boolean(opts.includeNotes) }),
     view,
   );
 }
 
-// ── Flag → API options translators ───────────────────────────────────────────
+// ── Flag → verb opts translators ─────────────────────────────────────────────
 
-function getFile(flags) {
-  const file = resolveFile({ file: flags.file }).file;
-  exitContext.file = file;
-  return file;
-}
 function hasGoto(flags) { return Object.prototype.hasOwnProperty.call(flags, 'goto'); }
 function gotoOpt(flags) { return hasGoto(flags) ? flags.goto : undefined; }
 
-function parsePlacement(flags, commandName) {
+function parsePlacement(ctx, flags, commandName) {
   const present = ['before', 'after', 'into'].filter((k) => flags[k] !== undefined);
   if (present.length === 0) return undefined;
-  if (present.length > 1) fail(`${commandName}: --before, --after, and --into are mutually exclusive`);
+  if (present.length > 1) fail(ctx, `${commandName}: --before, --after, and --into are mutually exclusive`);
   const kind = present[0];
   return { kind, anchor: flags[kind] };
 }
 
+function closeFlags(flags) {
+  return {
+    force: flags.force === true,
+    closeAll: flags['close-all'] === true,
+  };
+}
+
 // ── Command dispatch ─────────────────────────────────────────────────────────
 
-function cmdPush({ positional, flags }) {
+async function cmdPush(ctx, { positional, flags }) {
   const title = flags.title || positional.join(' ').trim();
-  const file = getFile(flags);
-  emitView(apiPush(file, { title }), flags);
+  const noggin = await ctx.openNoggin(flags);
+  emitView(ctx, await verbs.push(noggin, { title }), flags);
 }
 
-function cmdAdd({ positional, flags }) {
+async function cmdAdd(ctx, { positional, flags }) {
   const title = flags.title || positional.join(' ').trim();
-  const file = getFile(flags);
-  emitView(apiAdd(file, {
+  const noggin = await ctx.openNoggin(flags);
+  emitView(ctx, await verbs.add(noggin, {
     title,
-    placement: parsePlacement(flags, 'add'),
+    placement: parsePlacement(ctx, flags, 'add'),
     goto: gotoOpt(flags),
   }), flags);
 }
 
-function cmdMove({ positional, flags }) {
-  if (positional.length > 1) fail('move: accepts at most one path');
-  const file = getFile(flags);
-  emitView(apiMove(file, {
+async function cmdMove(ctx, { positional, flags }) {
+  if (positional.length > 1) fail(ctx, 'move: accepts at most one path');
+  const noggin = await ctx.openNoggin(flags);
+  emitView(ctx, await verbs.move(noggin, {
     path: positional[0],
-    placement: parsePlacement(flags, 'move'),
+    placement: parsePlacement(ctx, flags, 'move'),
     goto: gotoOpt(flags),
   }), flags);
 }
 
-function cmdGoto({ positional, flags }) {
-  if (!positional[0]) fail('goto: path required');
-  const file = getFile(flags);
-  emitView(apiGoto(file, { path: positional[0] }), flags);
-}
-
-function closeFlags(flags) {
-  return {
-    force: flags.force === true,
-    closeAll: flags['close-all'] === true,
-  };
+async function cmdGoto(ctx, { positional, flags }) {
+  if (!positional[0]) fail(ctx, 'goto: path required');
+  const noggin = await ctx.openNoggin(flags);
+  emitView(ctx, await verbs.goto(noggin, { path: positional[0] }), flags);
 }
 
-function cmdDone({ positional, flags }) {
-  if (positional.length > 1) fail('done: accepts at most one path');
-  const file = getFile(flags);
-  emitView(apiDone(file, {
+async function cmdDone(ctx, { positional, flags }) {
+  if (positional.length > 1) fail(ctx, 'done: accepts at most one path');
+  const noggin = await ctx.openNoggin(flags);
+  emitView(ctx, await verbs.done(noggin, {
     path: positional[0],
     ...closeFlags(flags),
     ...(hasGoto(flags) ? { goto: flags.goto } : {}),
   }), flags);
 }
 
-function cmdPop({ positional, flags }) {
-  if (positional.length > 0) fail('pop: takes no path; pop always operates on the active item');
-  if (hasGoto(flags)) fail('pop: --goto is not supported; pop always moves to the active item\'s parent');
-  const file = getFile(flags);
-  emitView(apiPop(file, closeFlags(flags)), flags);
+async function cmdPop(ctx, { positional, flags }) {
+  if (positional.length > 0) fail(ctx, 'pop: takes no path; pop always operates on the active item');
+  if (hasGoto(flags)) fail(ctx, "pop: --goto is not supported; pop always moves to the active item's parent");
+  const noggin = await ctx.openNoggin(flags);
+  emitView(ctx, await verbs.pop(noggin, closeFlags(flags)), flags);
 }
 
-function cmdEdit({ positional, flags }) {
+async function cmdEdit(ctx, { positional, flags }) {
   if (flags.done === true && flags.open === true) {
-    fail('edit: --done and --open are mutually exclusive');
+    fail(ctx, 'edit: --done and --open are mutually exclusive');
   }
-  if (positional.length > 1) fail('edit: accepts at most one path');
-  const file = getFile(flags);
+  if (positional.length > 1) fail(ctx, 'edit: accepts at most one path');
+  const noggin = await ctx.openNoggin(flags);
   const opts = {
     path: positional[0],
     goto: gotoOpt(flags),
@@ -305,18 +288,18 @@ function cmdEdit({ positional, flags }) {
   if (flags.done === true) opts.done = true;
   else if (flags.open === true) opts.done = false;
   if (flags.title !== undefined) opts.title = flags.title;
-  emitView(apiEdit(file, opts), flags);
+  emitView(ctx, await verbs.edit(noggin, opts), flags);
 }
 
-function cmdShow({ positional, flags }) {
-  const file = getFile(flags);
+async function cmdShow(ctx, { positional, flags }) {
+  const noggin = await ctx.openNoggin(flags);
   const withSiblings = flags['with-siblings'] === true || flags['with-all'] === true;
   const withDescendants = flags['with-descendants'] === true || flags['with-all'] === true;
   const noChildren = flags['no-children'] === true;
   if (withDescendants && noChildren) {
-    fail('show: --with-descendants and --no-children are mutually exclusive');
+    fail(ctx, 'show: --with-descendants and --no-children are mutually exclusive');
   }
-  const view = apiShow(file, {
+  const view = await verbs.show(noggin, {
     path: positional[0],
     includeChildren: !noChildren,
     withSiblings,
@@ -324,64 +307,101 @@ function cmdShow({ positional, flags }) {
     goto: gotoOpt(flags),
   });
   if (view === null) {
-    emitOutput(flags, () => process.stdout.write('(no active item; pass a path)\n'), null);
+    emitOutput(ctx, flags, () => ctx.io.stdout('(no active item; pass a path)\n'), null);
     return;
   }
-  emitView(view, flags, { includeNotes: flags['with-notes'] === true });
+  emitView(ctx, view, flags, { includeNotes: flags['with-notes'] === true });
 }
 
-function cmdNote({ positional, flags }) {
-  const file = getFile(flags);
+async function cmdNote(ctx, { positional, flags }) {
+  const noggin = await ctx.openNoggin(flags);
   let pathArg;
   let textParts = positional;
   if (positional.length > 0 && looksLikePath(positional[0])) {
     pathArg = positional[0];
     textParts = positional.slice(1);
   }
-  emitView(apiNote(file, {
+  emitView(ctx, await verbs.note(noggin, {
     path: pathArg,
     text: textParts.join(' ').trim(),
     goto: gotoOpt(flags),
   }), flags);
 }
 
-function cmdDelete({ positional, flags }) {
-  if (hasGoto(flags)) fail('delete: --goto is not supported');
-  if (positional.length === 0) fail('delete: path required');
-  if (positional.length > 1) fail('delete: accepts at most one path');
-  const file = getFile(flags);
-  const result = apiDelete(file, {
+async function cmdDelete(ctx, { positional, flags }) {
+  if (hasGoto(flags)) fail(ctx, 'delete: --goto is not supported');
+  if (positional.length === 0) fail(ctx, 'delete: path required');
+  if (positional.length > 1) fail(ctx, 'delete: accepts at most one path');
+  const noggin = await ctx.openNoggin(flags);
+  const result = await verbs.delete(noggin, {
     path: positional[0],
     recursive: flags.recursive === true,
   });
   emitOutput(
+    ctx,
     flags,
     () => {
       const tail = result.descendantCount ? ` and ${result.descendantCount} descendant(s)` : '';
-      process.stdout.write(`deleted ${result.deleted.path}${tail}\n`);
-      if (result.view) printView(result.view);
-      else process.stdout.write('(tree is now empty)\n');
+      ctx.io.stdout(`deleted ${result.deleted.path}${tail}\n`);
+      if (result.view) printView(ctx, result.view);
+      else ctx.io.stdout('(tree is now empty)\n');
+    },
+    result,
+  );
+}
+
+async function cmdWhere(ctx, { flags }) {
+  const noggin = await ctx.openNoggin(flags);
+  const location = noggin.describe();
+  emitOutput(
+    ctx,
+    flags,
+    () => { ctx.io.stdout(`${location}\n`); },
+    location,
+  );
+}
+
+async function cmdCopy(ctx, { positional, flags }) {
+  // `noggin copy <from> <to>` — open both via the engine (separate from
+  // ctx.openNoggin which is tied to --noggin/$NOGGIN/default) and call
+  // verbs.copy. v1 is a whole-noggin append-only copy; see SKILL.md.
+  if (positional.length < 2) {
+    fail(ctx, 'copy: usage: noggin copy <from> <to>', 2, 'usage');
+  }
+  const [fromLoc, toLoc] = positional;
+  const source = await ctx.openNogginAt(fromLoc);
+  const dest = await ctx.openNogginAt(toLoc);
+  const result = await verbs.copy(source, dest, {});
+  emitOutput(
+    ctx,
+    flags,
+    () => {
+      ctx.io.stdout(`copied ${result.copied} item(s) from ${source.describe()} to ${dest.describe()}\n`);
     },
     result,
   );
 }
 
-function cmdWhere({ flags }) {
-  const info = apiWhere({ file: flags.file });
-  exitContext.file = info.file;
+async function cmdFactories(ctx, { flags }) {
+  const list = factories.list();
   emitOutput(
+    ctx,
     flags,
     () => {
-      process.stdout.write(`${info.file}\n`);
-      process.stdout.write(`  source: ${info.source}\n`);
-      process.stdout.write(`  exists: ${info.exists}\n`);
+      if (list.length === 0) { ctx.io.stdout('(no factories registered)\n'); return; }
+      const w = Math.max(...list.map((f) => f.scheme.length), 6);
+      ctx.io.stdout(`${'scheme'.padEnd(w)}  default\n`);
+      ctx.io.stdout(`${'-'.repeat(w)}  -------\n`);
+      for (const f of list) {
+        ctx.io.stdout(`${f.scheme.padEnd(w)}  ${f.default ? 'yes' : ''}\n`);
+      }
     },
-    info,
+    list,
   );
 }
 
-function cmdHelp() {
-  process.stdout.write([
+async function cmdHelp(ctx) {
+  ctx.io.stdout([
     'noggin — working-memory tree CLI',
     '',
     'An item has: title, done flag, timestamps, and append-only notes.',
@@ -419,64 +439,179 @@ function cmdHelp() {
     '  note [<path>] <text…> [--goto [path]]',
     '                                  append a timestamped note',
     '  delete <path> [--recursive]     remove an item; --recursive also removes its subtree',
-    '  where                           print which noggin file would be used and why',
+    '  where                           print which noggin would be used and why',
+    '  copy <from> <to>                append every item from <from> into <to> (whole-noggin, append-only, fresh keys; notes and timestamps preserved)',
+    '  factories                       list registered backend factories',
     '  help',
     '',
     'Item creation flags (push/add):',
     '  --title T                       title (alternative to positional)',
     '',
     'Common:',
-    '  --file <path>                   override the file resolution (highest priority)',
+    '  --noggin <location>             override the noggin location (highest priority)',
     '  --goto [path]                   move after command; relative paths resolve from target',
     '  --json                          structured output',
     '  --with-json                     human output followed by structured output',
     '',
-    'File resolution (highest first):',
-    '  1. --file <path>',
-    `  2. $NOGGIN_FILE env var`,
-    `  3. ${DEFAULT_FILE}`,
+    'Noggin location (highest first):',
+    '  1. --noggin <location>',
+    '  2. $NOGGIN env var',
+    `  3. ${ctx.defaultLocationLabel}`,
+    '',
+    'Locations may be a bare path (defaults to the file backend) or a',
+    'URI like `file:///abs/path.yaml`. Run `noggin factories` to see all',
+    'registered backends.',
     '',
   ].join('\n'));
 }
 
-// ── Main ─────────────────────────────────────────────────────────────────────
+// ── Embedding entry point ───────────────────────────────────────────────────
+//
+// `runCommand(argv, opts)` is the engine of the CLI. It accepts an array
+// of argv tokens (no program name; just what would come after `noggin`)
+// and a bundle of injected dependencies, and returns the exit code.
+//
+//   opts.io.stdout(str)        — write a chunk of stdout text
+//   opts.io.stderr(str)        — write a chunk of stderr text
+//   opts.io.exit(code)         — optional; called with the final exit code
+//   opts.openNoggin(flags)     — async (flags) => Noggin; resolves the backend
+//   opts.openNogginAt(location)— optional; async (location) => Noggin; opens an arbitrary
+//                                location (used by `copy` which needs two noggins at once)
+//   opts.defaultLocationLabel  — optional; string shown in help text as
+//                                the default noggin location
+//
+// When `openNoggin`/`openNogginAt`/`defaultLocationLabel` are omitted
+// the node file backend is loaded lazily (so a browser bundle that
+// supplies its own openNoggin never pulls in `node:fs` et al.).
+
+export async function runCommand(argv, opts = {}) {
+  const io = opts.io || defaultNodeIo();
+  const openNogginFn = opts.openNoggin || await defaultNodeOpenNoggin();
+  const openNogginAtFn = opts.openNogginAt || await defaultNodeOpenNogginAt();
+  const defaultLocationLabel = opts.defaultLocationLabel
+    || (opts.openNoggin ? '(injected)' : await defaultNodeLocationLabel());
+  const ctx = {
+    verb: null,
+    json: false,
+    io,
+    openNoggin: openNogginFn,
+    openNogginAt: openNogginAtFn,
+    defaultLocationLabel,
+  };
+
+  let exitCode = 0;
+  try {
+    if (!argv || argv.length === 0) { await cmdHelp(ctx); return finish(io, 0); }
+    const { verb, args } = splitCommand(ctx, argv);
+    const parsed = parseArgs(ctx, args);
+    ctx.verb = verb || null;
+    ctx.json = Boolean(parsed.flags.json);
+    if (parsed.flags.help) { await cmdHelp(ctx); return finish(io, 0); }
+    try {
+      await dispatch(ctx, verb, parsed);
+    } catch (e) {
+      if (e instanceof NogginError) {
+        fail(ctx, e.message, e.exitCode, e.code);
+      }
+      throw e;
+    }
+  } catch (e) {
+    if (e instanceof ExitSignal) {
+      exitCode = e.code;
+    } else {
+      io.stderr(`noggin: ${e && e.message ? e.message : e}\n`);
+      exitCode = 1;
+    }
+  }
+  return finish(io, exitCode);
+}
+
+function finish(io, code) {
+  if (typeof io.exit === 'function') io.exit(code);
+  return code;
+}
 
-function dispatch(verb, parsed) {
+async function dispatch(ctx, verb, parsed) {
   switch (verb) {
-    case 'push':      return cmdPush(parsed);
-    case 'add':       return cmdAdd(parsed);
-    case 'move':      return cmdMove(parsed);
-    case 'goto':      return cmdGoto(parsed);
-    case 'done':      return cmdDone(parsed);
-    case 'pop':       return cmdPop(parsed);
-    case 'edit':      return cmdEdit(parsed);
-    case 'show':      return cmdShow(parsed);
-    case 'note':      return cmdNote(parsed);
-    case 'delete':    return cmdDelete(parsed);
-    case 'where':     return cmdWhere(parsed);
+    case 'push':      return await cmdPush(ctx, parsed);
+    case 'add':       return await cmdAdd(ctx, parsed);
+    case 'move':      return await cmdMove(ctx, parsed);
+    case 'goto':      return await cmdGoto(ctx, parsed);
+    case 'done':      return await cmdDone(ctx, parsed);
+    case 'pop':       return await cmdPop(ctx, parsed);
+    case 'edit':      return await cmdEdit(ctx, parsed);
+    case 'show':      return await cmdShow(ctx, parsed);
+    case 'note':      return await cmdNote(ctx, parsed);
+    case 'delete':    return await cmdDelete(ctx, parsed);
+    case 'where':     return await cmdWhere(ctx, parsed);
+    case 'copy':      return await cmdCopy(ctx, parsed);
+    case 'factories': return await cmdFactories(ctx, parsed);
     case 'help':
     case '--help':
-    case '-h':        cmdHelp(); return;
-    default:          fail(`unknown command: ${verb} (try 'help')`);
+    case '-h':        await cmdHelp(ctx); return;
+    default:          fail(ctx, `unknown command: ${verb} (try 'help')`);
   }
 }
 
-function main() {
-  const argv = process.argv.slice(2);
-  if (argv.length === 0) { cmdHelp(); process.exit(0); }
-  const { verb, args } = splitCommand(argv);
-  const parsed = parseArgs(args);
-  exitContext.verb = verb || null;
-  exitContext.json = Boolean(parsed.flags.json);
-  if (parsed.flags.help) { cmdHelp(); process.exit(0); }
-  try {
-    dispatch(verb, parsed);
-  } catch (e) {
-    if (e instanceof NogginError) {
-      fail(e.message, e.exitCode, e.code);
-    }
-    throw e;
-  }
+// ── Lazy node defaults ──────────────────────────────────────────────────────
+//
+// These helpers are only invoked when the caller leaves the matching
+// opt unset. The dynamic import of `./backends/file.mjs` means a browser
+// bundle that always passes its own io/openNoggin never pulls in
+// `node:fs`/`node:os`/`node:path`.
+
+function defaultNodeIo() {
+  return {
+    stdout: (s) => process.stdout.write(s),
+    stderr: (s) => process.stderr.write(s),
+    exit: (code) => process.exit(code),
+  };
+}
+
+/**
+ * Default openNoggin(flags): resolves the location by the standard
+ * priority and opens via the engine's factory registry. Imports the
+ * file backend for side-effect (registers the file:// factory).
+ */
+async function defaultNodeOpenNoggin() {
+  await import('./backends/file.mjs');
+  const { openNoggin } = await import('./noggin-api.mjs');
+  const defaultLoc = await defaultNodeLocationLabel();
+  return (flags) => openNoggin(resolveLocation(flags, defaultLoc));
 }
 
-main();
+/**
+ * Default openNogginAt(location): opens an explicit location string
+ * via the engine. Used by `copy` and any other verb that needs to
+ * open a noggin from a path argument rather than the resolved
+ * --noggin/$NOGGIN/default. Imports the file backend side-effect
+ * the same way as defaultNodeOpenNoggin.
+ */
+async function defaultNodeOpenNogginAt() {
+  await import('./backends/file.mjs');
+  const { openNoggin } = await import('./noggin-api.mjs');
+  return (location) => openNoggin(location);
+}
+
+async function defaultNodeLocationLabel() {
+  // The default noggin location is `~/.noggin.yaml` in canonical form.
+  // The file backend's expandHome() turns this into the actual home dir
+  // at open time, but the *location string* stays symbolic so `where`
+  // shows the human-readable form.
+  return '~/.noggin.yaml';
+}
+
+function resolveLocation(flags, defaultLocation) {
+  if (flags && flags.noggin) return flags.noggin;
+  if (typeof process !== 'undefined' && process.env && process.env.NOGGIN) return process.env.NOGGIN;
+  return defaultLocation;
+}
+
+// ── Shebang main ────────────────────────────────────────────────────────────
+
+if (typeof process !== 'undefined' && Array.isArray(process.argv)) {
+  runCommand(process.argv.slice(2)).catch((e) => {
+    process.stderr.write(`noggin: ${e && e.message ? e.message : e}\n`);
+    process.exit(1);
+  });
+}