@agentage/cli 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to Agentage CLI will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.0.4] - 2026-07-09
+
+### Breaking
+
+- Removed the standalone `agentage mcp` stdio command. MCP is now served by the local daemon over Streamable HTTP at `http://127.0.0.1:4243/mcp` (on by default; disable with `daemon start --no-mcp` or `AGENTAGE_DAEMON_NO_MCP=1`). Point clients at the daemon URL: `claude mcp add --transport http agentage http://127.0.0.1:4243/mcp`.
+
+### New Features
+
+- Account sync: the daemon syncs account (cloud) vaults, with live autodiscovery of new vaults and account-vault provisioning.
+- `setup` now starts the daemon after a successful sign-in, so sync and MCP are ready immediately.
+- `status` now reports the daemon (pid, port, uptime), MCP serving state, a `target` reachability check, and a per-vault breakdown (name, sync channel, status).
+- Outgoing requests now identify the caller with `User-Agent` and CLI/daemon version headers.
+
+### Improvements
+
+- Auth: sessions refresh silently; a transient auth-server hiccup (429/5xx/network) is retried instead of being reported as a signed-out session.
+- A credential for a different environment than the current target is now reported as an env mismatch (with a recovery hint), not a misleading "session expired".
+- `status` auth line reads `signed in (session active)` rather than a raw UTC token-expiry timestamp.
+- README rewritten for non-technical readers, with the full command and integration reference moved to `docs/reference.md`.
+- Daemon hardened against CSRF and DNS rebinding on its local API; lifecycle and port-in-use races fixed.
+- Sync: remote-URL allowlist and redaction; channel-based internal structure.
+- Offline commands no longer hang; cleaner stdout/stderr discipline.
+
+### Fixed
+
+- Data integrity: concurrent writers can no longer silently drop registry updates. The advisory file lock now creates atomically (write-then-link) and never steals a live holder's lock under CPU contention.
+- Packaging hygiene: dependency pins, trimmed npm tarball, removed tracked build artifacts.
+
+### Internal
+
+- `src/lib` and `src/commands` regrouped into domain folders; oversized modules split.
+
+## [0.0.3] - 2026-06-27
+
+### Fixed
+
+- `status` now reaches the backend at the dedicated `api.<fqdn>` host (the apex `<fqdn>/api` was retired in the 2026-06-17 subdomain cutover), so production no longer reports the endpoint unreachable.
+- `status` no longer crashes when the bearer maps to no active session (`get-session` returns `200 + null`); it now reports signed-out with a `run: agentage setup` hint.
+
+## [0.0.2] - 2026-06-26
+
+### New Features
+- Add `setup` and `status` commands as part of the agentage Memory client reboot
+- Add daemon autostart on boot/login (platform-aware configuration)
+- Handle machine tombstoned state (410 response) gracefully in the daemon
+
+### Improvements
+- Route daemon version-mismatch notice and update notice to stderr for cleaner stdout output
+- Reduce update-check cache from 24h to 1h for more timely update notifications
+
+## [0.0.1] - 2026-06-12
+
+### Added
+
+- `setup` - browser OAuth 2.1 sign-in (Dynamic Client Registration + PKCE) with a
+  localhost callback; tokens stored in `~/.agentage/auth.json` (mode 0600); flags:
+  `--disconnect`, `--reauth`, `--no-browser`.
+- `status` - one line per fact: CLI version, target, sign-in state, and endpoint
+  reachability (`--json` supported).

package/README.md

@@ -3,54 +3,96 @@
 [![CI](https://github.com/agentage/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/agentage/cli/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/%40agentage%2Fcli.svg)](https://badge.fury.io/js/%40agentage%2Fcli)
 
-The [agentage](https://agentage.io) command line.
+Give every AI on your machine one shared memory - plain markdown you own, synced across your devices.
 
-## Install
+Claude, Cursor, and your other AI tools each keep their own separate memory today. This
+CLI gives them a single shared one. It lives on your disk as ordinary markdown files
+you can open, edit, and back up like any other folder. Your AI tools read and write
+those same files, so they all remember the same things. Connect a free account and your
+memory follows you to every device - and nothing is locked in, because the files are
+always just markdown you can export.
+
+## How it fits together
+
+![Architecture](https://github.com/agentage/cli/raw/master/docs/architecture.svg)
+
+## Quickstart
+
+Three steps from nothing to a shared memory your AI can use.
+
+**1. Install it.** Needs Node.js 22 or newer.
 
 ```bash
 npm install -g @agentage/cli
 ```
 
-Requires Node.js >= 22.
+**2. Create a memory.** This makes a plain folder of markdown files at `~/vaults/notes`.
+No sign-in needed.
 
-## Commands
-
-### `agentage setup`
+```bash
+agentage vault add notes --local
+```
 
-Signs this machine in to your agentage account. Opens a browser for OAuth 2.1
-sign-in (PKCE) and stores the resulting tokens in `~/.agentage/auth.json`
-(mode 0600). No passwords ever touch the terminal.
+**3. Connect your AI.** This example wires up Claude Code over MCP, the open protocol AI
+tools use to call tools. Any AI tool that speaks MCP connects the same way.
 
 ```bash
-agentage setup               # browser sign-in, then prints status
-agentage setup --no-browser  # print the sign-in URL instead of opening a browser
-agentage setup --reauth      # force a fresh sign-in
-agentage setup --disconnect  # sign out and remove local credentials
+claude mcp add --transport http agentage http://127.0.0.1:4243/mcp
 ```
 
-### `agentage status`
+That's it. Ask your AI to remember something, and it lands in your `~/vaults/notes`
+folder as a markdown file you own.
+
+## What your AI can do
+
+Once connected, your AI can:
 
-Shows this machine's connection, one line per fact: CLI version, target,
-sign-in state, and endpoint reachability.
+- Remember things you tell it, saved as a note.
+- Find them again later by keyword.
+- Read back a specific note in full.
+- Update a note in place, or add to it.
+- Browse the folders your notes are organized into.
+- Remove a note it no longer needs (deletes are recoverable).
+
+You can do all of this from the terminal too - run `agentage memory --help` to see how.
+
+## Sync across devices
+
+Want the same memory on your laptop, desktop, and phone? Connect a free account:
 
 ```bash
-agentage status
-agentage status --json
+agentage setup
 ```
 
-## Environment
+This opens your browser for a one-time sign-in - no API key to copy or passwords in the
+terminal. After that, sync runs quietly in the background and the same memory follows
+you everywhere. Your files always stay yours: they remain plain markdown on your disk,
+and you can export them any time.
+
+Prefer to host it yourself? You can point a memory at your own git remote instead with
+`agentage vault add <name> --git <remote>` - see [`docs/reference.md`](docs/reference.md)
+for details.
+
+## Going deeper
 
-| Variable              | Purpose                     | Default       |
-| --------------------- | --------------------------- | ------------- |
-| `AGENTAGE_SITE_FQDN`  | Target host                 | `agentage.io` |
-| `AGENTAGE_CONFIG_DIR` | Credential/config directory | `~/.agentage` |
+- [`docs/architecture.md`](docs/architecture.md) - how the CLI, the local helper, your
+  files, and sync fit together.
+- [`docs/reference.md`](docs/reference.md) - every command and flag, the full sync
+  options, MCP details, and environment variables.
 
 ## Development
 
 ```bash
 npm ci
-npm run verify                    # type-check + lint + format + unit tests + build
-npm run build && npm run test:e2e # live e2e (Playwright) against the dev stack
+npm run verify        # type-check + lint + format:check + unit tests + build
+```
+
+End-to-end tests (Playwright) run in tiers - the offline tiers need no network or
+account. See [`docs/reference.md`](docs/reference.md) for more.
+
+```bash
+npm run build && npm run test:e2e                      # all e2e tiers
+npm run build && npm run test:e2e -- --grep @offline   # offline tiers only
 ```
 
 ## License

package/dist/cli.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,14 +1,54 @@
 #!/usr/bin/env node
+import chalk from 'chalk';
 import { Command } from 'commander';
-import { registerSetup } from './commands/setup.js';
-import { registerStatus } from './commands/status.js';
+import { registerDaemon } from './commands/daemon/daemon-cmd.js';
+import { registerMemory } from './commands/memory/memory.js';
+import { registerSetup } from './commands/auth/setup.js';
+import { registerStatus } from './commands/status/status.js';
+import { registerUpdate } from './commands/update/update.js';
+import { registerVault } from './commands/vault/vault.js';
+import { disableDaemon } from './lib/daemon/daemon-pref.js';
+import { refreshUpdateCache, updateHint } from './lib/update/update-cache.js';
 import { VERSION } from './utils/version.js';
+// Dependency-free guard so the message survives even if deps fail to parse on old Node.
+const nodeMajor = Number(process.versions.node.split('.')[0]);
+if (nodeMajor < 22) {
+    process.stderr.write(`agentage requires Node.js >= 22 (you have v${process.versions.node})\n`);
+    process.exit(1);
+}
 const program = new Command();
-program.name('agentage').description('The agentage CLI').version(VERSION);
+program
+    .name('agentage')
+    .description('The offline-first terminal client for agentage Memory')
+    .version(VERSION)
+    .option('--no-daemon', 'run memory verbs in-process instead of via the daemon');
+program.addHelpText('after', '\nNew here? Run: agentage vault add <name> --local, or agentage setup to connect an account.');
+program.hook('preAction', () => {
+    if (program.opts().daemon === false)
+        disableDaemon();
+});
+// After any command (except the update-aware ones, which report richer state themselves), print a
+// one-line hint from the cache, then kick a fire-and-forget refresh. Never awaited, never throws -
+// the command output is already done and the cache-only read keeps this instant. The hint is
+// suppressed under --json so it never corrupts machine-readable output.
+program.hook('postAction', (_thisCommand, actionCommand) => {
+    const name = actionCommand.name();
+    if (name === 'status' || name === 'update')
+        return;
+    if (!actionCommand.opts()['json']) {
+        const hint = updateHint();
+        if (hint)
+            console.error(chalk.dim(hint)); // stderr: never corrupt piped stdout
+    }
+    void refreshUpdateCache();
+});
 registerSetup(program);
 registerStatus(program);
+registerVault(program);
+registerMemory(program);
+registerDaemon(program);
+registerUpdate(program);
 program.parseAsync().catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
 });
-//# sourceMappingURL=cli.js.map

package/dist/commands/{setup.d.ts → auth/setup.d.ts}

@@ -1,6 +1,8 @@
 import { type Command } from 'commander';
-import { startCallbackServer } from '../lib/callback-server.js';
-import { exchangeCode, registerClient, revokeToken } from '../lib/oauth.js';
+import { startCallbackServer } from '../../lib/auth/callback-server.js';
+import { ensureDaemon } from '../../lib/daemon/daemon-client.js';
+import { introspectToken } from '../../lib/auth/api.js';
+import { exchangeCode, registerClient, revokeToken } from '../../lib/auth/oauth.js';
 export interface SetupOptions {
     disconnect?: boolean;
     reauth?: boolean;
@@ -13,7 +15,8 @@ export interface SetupDeps {
     startServer: typeof startCallbackServer;
     openBrowser: (url: string) => Promise<void>;
     printStatus: () => Promise<void>;
+    ensureDaemon: typeof ensureDaemon;
+    introspect: typeof introspectToken;
 }
 export declare const runSetup: (opts: SetupOptions, deps?: SetupDeps) => Promise<void>;
 export declare const registerSetup: (program: Command) => void;
-//# sourceMappingURL=setup.d.ts.map

package/dist/commands/{setup.js → auth/setup.js}

@@ -1,9 +1,14 @@
 import chalk from 'chalk';
-import { startCallbackServer } from '../lib/callback-server.js';
-import { deleteAuth, ensureConfigDir, readAuth, saveAuth } from '../lib/config.js';
-import { buildAuthorizeUrl, exchangeCode, pkcePair, randomState, registerClient, revokeToken, } from '../lib/oauth.js';
-import { links, siteFqdn } from '../lib/origins.js';
-import { runStatus } from './status.js';
+import { startCallbackServer } from '../../lib/auth/callback-server.js';
+import { ensureDaemon } from '../../lib/daemon/daemon-client.js';
+import { daemonDisabled } from '../../lib/daemon/daemon-pref.js';
+import { deleteAuth, ensureConfigDir, mutateAuth, readAuth, } from '../../lib/fs/config.js';
+import { AuthRequiredError, introspectToken } from '../../lib/auth/api.js';
+import { detectEnvMismatch } from '../../lib/auth/env-match.js';
+import { buildAuthorizeUrl, exchangeCode, pkcePair, randomState, registerClient, revokeToken, } from '../../lib/auth/oauth.js';
+import { links, siteFqdn } from '../../lib/net/origins.js';
+import { ensureVaultsConfig } from '../../lib/vault/vaults.js';
+import { runStatus } from '../status/status.js';
 const defaultDeps = {
     register: registerClient,
     exchange: exchangeCode,
@@ -14,6 +19,8 @@ const defaultDeps = {
         await open(url);
     },
     printStatus: () => runStatus({}),
+    ensureDaemon,
+    introspect: introspectToken,
 };
 const toAuthState = (fqdn, clientId, tokens) => ({
     siteFqdn: fqdn,
@@ -24,6 +31,18 @@ const toAuthState = (fqdn, clientId, tokens) => ({
         expiresAt: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : undefined,
     },
 });
+// After sign-in, bring the daemon up so account sync starts immediately; ensureDaemon reuses a
+// live daemon and starts a stopped one (idempotent). Honor the --no-daemon / AGENTAGE_NO_DAEMON
+// disable switches.
+const startDaemon = async (deps) => {
+    if (daemonDisabled()) {
+        console.log('Daemon disabled - account sync will run in-process on demand.');
+        return;
+    }
+    const client = await deps.ensureDaemon();
+    const fail = 'Could not start the daemon - run: agentage daemon start';
+    console.log(client ? 'Daemon running.' : fail);
+};
 const disconnect = async (deps) => {
     const auth = readAuth();
     if (!auth) {
@@ -34,19 +53,45 @@ const disconnect = async (deps) => {
     deleteAuth();
     console.log('Disconnected - local credentials removed.');
 };
+// Validate the stored session instead of trusting mere token presence. Returns true to short-circuit
+// (valid or a transient blip - creds intact), false to proceed into a fresh sign-in (truly expired or
+// the credential belongs to a different target than the current run).
+const alreadySignedIn = async (auth, deps) => {
+    const mismatch = detectEnvMismatch(auth, siteFqdn());
+    if (mismatch) {
+        console.log(`Signed in to ${mismatch.credentialFqdn} (${mismatch.credentialEnv}), but this run targets ` +
+            `${mismatch.targetFqdn} (${mismatch.targetEnv}) - signing you into ${mismatch.targetEnv}.\n`);
+        return false; // proceed to a fresh sign-in against the current target
+    }
+    try {
+        await deps.introspect(auth, links(auth.siteFqdn));
+        console.log(`Already signed in. Run ${chalk.white('agentage setup --reauth')} to sign in again.\n`);
+        await deps.printStatus();
+        return true;
+    }
+    catch (err) {
+        if (err instanceof AuthRequiredError) {
+            console.log('Session expired - signing you in again.\n');
+            return false; // fall through to the sign-in flow, no --reauth needed
+        }
+        // Transient: do not force reauth on a blip; keep credentials and show status.
+        console.log('You appear signed in (could not fully verify - temporary).\n');
+        await deps.printStatus();
+        return true;
+    }
+};
 export const runSetup = async (opts, deps = defaultDeps) => {
     if (opts.disconnect) {
         await disconnect(deps);
         return;
     }
-    if (readAuth() && !opts.reauth) {
-        console.log(`Already signed in. Run ${chalk.white('agentage setup --reauth')} to sign in again.\n`);
-        await deps.printStatus();
+    const stored = readAuth();
+    if (stored && !opts.reauth && (await alreadySignedIn(stored, deps)))
         return;
-    }
     const fqdn = siteFqdn();
     const target = links(fqdn);
     ensureConfigDir();
+    ensureVaultsConfig();
     const { verifier, challenge } = pkcePair();
     const state = randomState();
     const server = await deps.startServer(state);
@@ -73,8 +118,9 @@ export const runSetup = async (opts, deps = defaultDeps) => {
             redirectUri: server.redirectUri,
             verifier,
         });
-        saveAuth(toAuthState(fqdn, clientId, tokens));
+        await mutateAuth(() => toAuthState(fqdn, clientId, tokens));
         console.log(chalk.green('\nSigned in.\n'));
+        await startDaemon(deps);
         await deps.printStatus();
     }
     finally {
@@ -99,4 +145,3 @@ export const registerSetup = (program) => {
         }
     });
 };
-//# sourceMappingURL=setup.js.map

package/dist/commands/daemon/daemon-cmd.d.ts

@@ -0,0 +1,2 @@
+import { type Command } from 'commander';
+export declare const registerDaemon: (program: Command) => void;

package/dist/commands/daemon/daemon-cmd.js

@@ -0,0 +1,124 @@
+import chalk from 'chalk';
+import { isDaemonRunning, resolvePort, signalPid, stopDaemonSafely, } from '../../daemon/lifecycle.js';
+import { health, mismatchNotice, spawnDaemon, syncStatus } from '../../lib/daemon/daemon-client.js';
+const startAction = async (opts = {}) => {
+    const port = resolvePort();
+    const existing = await health(port);
+    if (existing) {
+        console.log(chalk.gray(`Daemon already running (pid ${existing.pid}, port ${port}).`));
+        return;
+    }
+    const noMcp = opts.mcp === false;
+    const outcome = await spawnDaemon(port, { noMcp });
+    if (!outcome.ok) {
+        if (outcome.reason === 'port-in-use') {
+            console.error(chalk.red(`Port ${port} is in use by another process - set AGENTAGE_DAEMON_PORT to use a different port.`));
+        }
+        else {
+            console.error(chalk.red('Daemon failed to start.'));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const h = await health(port);
+    const mcp = noMcp ? 'off' : 'on';
+    console.log(chalk.green(`Daemon started (pid ${h?.pid ?? '?'}, port ${port}, mcp ${mcp}).`));
+};
+// Detect the daemon the same way `start` does (tokenless /health), so a legacy daemon that never
+// wrote this config dir's pidfile is not misreported as "not running". With a pidfile we own, use
+// the safe pid-confirming stop; otherwise fall back to signalling the pid /health reports, or - if
+// none is available - report the truth rather than a false "not running".
+const stopAction = async () => {
+    if (isDaemonRunning()) {
+        if (await stopDaemonSafely())
+            console.log(chalk.green('Daemon stopped.'));
+        return;
+    }
+    const port = resolvePort();
+    const h = await health(port);
+    if (!h) {
+        console.log(chalk.gray('Daemon is not running.'));
+        return;
+    }
+    if (typeof h.pid === 'number' && signalPid(h.pid)) {
+        console.log(chalk.green(`Daemon stopped (pid ${h.pid}).`));
+        return;
+    }
+    const who = typeof h.pid === 'number' ? `pid ${h.pid}` : `port ${port}`;
+    console.error(chalk.yellow(`Daemon is running (${who}) but has no pidfile to stop it safely; stop it with: kill ${h.pid ?? '<pid>'}`));
+    process.exitCode = 1;
+};
+const statusAction = async () => {
+    const port = resolvePort();
+    const h = await health(port);
+    if (!h) {
+        console.log(isDaemonRunning()
+            ? chalk.yellow(`Daemon pid file present but unreachable on port ${port}.`)
+            : chalk.gray('Daemon is not running.'));
+        return;
+    }
+    console.log(`pid      ${h.pid ?? '?'}`);
+    console.log(`port     ${port}`);
+    if (typeof h.uptime === 'number')
+        console.log(`uptime   ${h.uptime}s`);
+    if (typeof h.served === 'number')
+        console.log(`served   ${h.served}`);
+    console.log(`mcp      ${h.mcp === false ? 'off' : 'on'}`);
+    console.log(`version  ${h.version}`);
+    const notice = mismatchNotice(h.version);
+    if (notice)
+        console.log(chalk.yellow(notice));
+    const sync = await syncStatus(port);
+    if (sync && sync.vaults.length > 0) {
+        console.log('sync');
+        for (const v of sync.vaults) {
+            const cadence = v.intervalSeconds > 0 ? `every ${v.intervalSeconds}s` : 'manual';
+            const state = v.running
+                ? 'running'
+                : v.lastError
+                    ? `error: ${v.lastError}`
+                    : v.lastRun
+                        ? `ok ${v.lastRun}`
+                        : 'scheduled';
+            console.log(`  ${v.vault.padEnd(16)} ${cadence.padEnd(12)} ${state}`);
+        }
+    }
+    if (sync?.couch && sync.couch.length > 0) {
+        console.log('couch sync');
+        for (const v of sync.couch) {
+            const cadence = v.intervalSeconds > 0 ? `every ${v.intervalSeconds}s` : 'manual';
+            const state = v.paused
+                ? `paused: ${v.paused}`
+                : v.running
+                    ? 'running'
+                    : v.lastError
+                        ? `error: ${v.lastError}`
+                        : v.lastSync
+                            ? `ok ${v.lastSync}`
+                            : 'scheduled';
+            const pending = v.pendingCount > 0 ? `  ${v.pendingCount} pending` : '';
+            console.log(`  ${v.vault.padEnd(16)} ${cadence.padEnd(12)} ${state}${pending}`);
+        }
+    }
+    if (sync?.discover && sync.discover.roots.length > 0) {
+        console.log(`discover roots (${sync.discover.roots.length})`);
+        for (const root of sync.discover.roots)
+            console.log(`  ${root}`);
+    }
+};
+export const registerDaemon = (program) => {
+    const daemon = program.command('daemon').description('Manage the local engine daemon');
+    daemon
+        .command('start')
+        .description('Start the daemon (idempotent)')
+        .option('--no-mcp', 'do not serve the local MCP endpoint at /mcp')
+        .action((opts) => startAction(opts));
+    daemon
+        .command('stop')
+        .description('Stop the daemon')
+        .action(() => stopAction());
+    daemon
+        .command('status')
+        .description('Show the daemon pid, uptime, and version')
+        .action(() => statusAction());
+};

package/dist/commands/memory/memory-verbs.d.ts

@@ -0,0 +1,21 @@
+import { type MemoryClient } from '../../lib/memory/memory-client.js';
+export interface CommonOpts {
+    vault?: string;
+    json?: boolean;
+}
+export declare const runSearch: (query: string, opts: CommonOpts & {
+    limit?: string;
+}, client?: MemoryClient) => Promise<void>;
+export declare const runRead: (ref: string, opts: CommonOpts, client?: MemoryClient) => Promise<void>;
+export declare const runWrite: (ref: string, opts: CommonOpts & {
+    body?: string;
+    frontmatter?: string;
+}, client?: MemoryClient) => Promise<void>;
+export declare const runEdit: (ref: string, opts: CommonOpts & {
+    old?: string;
+    new?: string;
+    body?: string;
+    append?: boolean;
+}, client?: MemoryClient) => Promise<void>;
+export declare const runList: (folder: string | undefined, opts: CommonOpts, client?: MemoryClient) => Promise<void>;
+export declare const runDelete: (ref: string, opts: CommonOpts, client?: MemoryClient) => Promise<void>;

package/dist/commands/memory/memory-verbs.js

@@ -0,0 +1,98 @@
+import chalk from 'chalk';
+import { ensureDaemon } from '../../lib/daemon/daemon-client.js';
+import { daemonDisabled } from '../../lib/daemon/daemon-pref.js';
+import { createDirectClient } from '../../lib/memory/memory-client.js';
+import { loadVaultsConfig } from '../../lib/vault/vaults.js';
+// Default engine path (DO3/DO4): the daemon - single writer, autostarted - when reachable; the
+// in-process DirectClient as a seamless fallback (--no-daemon, sandbox/CI, or fork blocked).
+const resolveClient = async () => {
+    const direct = () => createDirectClient(loadVaultsConfig().config);
+    if (daemonDisabled())
+        return direct();
+    const daemon = await ensureDaemon();
+    return daemon ?? direct();
+};
+const readStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8');
+};
+// --frontmatter must be a JSON object; a raw parser error or a non-object value is unfriendly.
+const parseFrontmatter = (raw) => {
+    if (!raw)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`--frontmatter must be a JSON object, e.g. '{"tags":["x"]}': ${detail}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw new Error(`--frontmatter must be a JSON object, e.g. '{"tags":["x"]}'`);
+    return parsed;
+};
+const emit = (json, data, human) => {
+    if (json)
+        console.log(JSON.stringify(data, null, 2));
+    else
+        human();
+};
+// Flatten a folder-tree to the file paths it contains, in tree order.
+const treeFiles = (entries) => entries.flatMap((e) => (e.type === 'file' ? [e.path] : e.entries ? treeFiles(e.entries) : []));
+export const runSearch = async (query, opts, client) => {
+    const c = client ?? (await resolveClient());
+    const out = await c.search(query, {
+        vault: opts.vault,
+        limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined,
+    });
+    emit(opts.json ?? false, out, () => {
+        if (out.results.length === 0)
+            console.log('No matches.');
+        for (const h of out.results)
+            console.log(`${h.path}\n  ${chalk.gray(h.snippet)}`);
+    });
+};
+export const runRead = async (ref, opts, client) => {
+    const c = client ?? (await resolveClient());
+    const doc = await c.read(ref, { vault: opts.vault });
+    emit(opts.json ?? false, doc, () => console.log(doc.body));
+};
+export const runWrite = async (ref, opts, client) => {
+    const c = client ?? (await resolveClient());
+    const inlineBody = opts.body !== undefined && opts.body !== '-';
+    if (!inlineBody && process.stdin.isTTY)
+        throw new Error('provide --body, or pipe content on stdin');
+    const body = inlineBody ? opts.body : await readStdin();
+    const frontmatter = parseFrontmatter(opts.frontmatter);
+    const out = await c.write(ref, body, { vault: opts.vault, frontmatter });
+    emit(opts.json ?? false, out, () => console.log(chalk.green(`Wrote ${out.path}`)));
+};
+export const runEdit = async (ref, opts, client) => {
+    const c = client ?? (await resolveClient());
+    if (opts.old === undefined && opts.body === undefined)
+        throw new Error('specify --old/--new for a replacement or --body to overwrite');
+    const op = opts.old !== undefined
+        ? { mode: 'str_replace', old_str: opts.old, new_str: opts.new ?? '' }
+        : { mode: opts.append ? 'append' : 'replace', body: opts.body };
+    const out = await c.edit(ref, op, { vault: opts.vault });
+    emit(opts.json ?? false, out, () => console.log(chalk.green(`Edited ${out.path}`)));
+};
+export const runList = async (folder, opts, client) => {
+    const c = client ?? (await resolveClient());
+    const out = await c.list(folder, { vault: opts.vault });
+    emit(opts.json ?? false, out, () => {
+        const files = treeFiles(out.entries);
+        if (files.length === 0)
+            console.log('No documents.');
+        for (const p of files)
+            console.log(p);
+    });
+};
+export const runDelete = async (ref, opts, client) => {
+    const c = client ?? (await resolveClient());
+    const out = await c.delete(ref, { vault: opts.vault });
+    emit(opts.json ?? false, out, () => console.log(`Deleted ${out.path} (recoverable from git history)`));
+};

package/dist/commands/memory/memory.d.ts

@@ -0,0 +1,2 @@
+import { type Command } from 'commander';
+export declare const registerMemory: (program: Command) => void;