@tenphi/akno 0.1.0

package/dist/commands/write-cmd.js

@@ -0,0 +1,269 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import { openOptionsFrom, parse } from "../args.js";
+import { heading, json, kv, line, statusLabel, style, truncate } from "../output.js";
+import { resolveOps } from "../ops-handle.js";
+const WRITE_HELP = `akno write [options]
+
+  Create, append, patch or replace a page. Exactly one body option.
+
+  --slug <slug>         The page. Omit with --event for a ledger-only event.
+  --content <text>      Replace the whole body (or create the page).
+  --append <text>       Add to the end of the body.
+  --section <heading>   With --append: add at the end of that section instead. Errors
+                        when the page has no such heading, or more than one.
+  --replace <find>      With --with: replace one unique occurrence.
+  --with <text>
+  --patch <-|file>      A unified diff. Context must match exactly.
+  --event <YYYY-MM-DD=summary>
+                        Also append a timeline line, in the same change.
+  --title / --type / --tag <t,...> / --link <slug,...>
+                        Frontmatter for a page being created.
+  --attach <path[=label]>
+                        Attach a file, repeatable. It is copied in beside the page,
+                        named after it, and its text is extracted and indexed — so a
+                        PDF you attach is searchable by its own contents.
+  --actor <who>         user | agent. The user is never gated; default agent.
+  --resolve-conflict <token>
+                        Proceed past a conflict you have already asked about.
+  --dry-run             Report what would happen; touch nothing.
+  --json`;
+export async function writeCommand(argv) {
+    const { values } = parse(argv, {
+        slug: { type: 'string' },
+        content: { type: 'string' },
+        append: { type: 'string' },
+        section: { type: 'string' },
+        replace: { type: 'string' },
+        with: { type: 'string' },
+        patch: { type: 'string' },
+        event: { type: 'string' },
+        title: { type: 'string' },
+        type: { type: 'string' },
+        tag: { type: 'string' },
+        link: { type: 'string' },
+        attach: { type: 'string', multiple: true },
+        actor: { type: 'string' },
+        'resolve-conflict': { type: 'string' },
+        'dry-run': { type: 'boolean', default: false },
+    });
+    if (values.help) {
+        line(WRITE_HELP);
+        return 0;
+    }
+    const event = values.event ? parseEvent(values.event) : null;
+    if (values.event && !event) {
+        line(style.red('--event wants YYYY-MM-DD=summary'));
+        return 1;
+    }
+    if (values.replace !== undefined && values.with === undefined) {
+        line(style.red('--replace needs --with'));
+        return 1;
+    }
+    // `--patch -` reads stdin, because a diff is rarely something you type.
+    const patch = values.patch === '-'
+        ? await readStdin()
+        : values.patch
+            ? await fsp.readFile(values.patch, 'utf8').catch(() => values.patch)
+            : undefined;
+    const handle = await resolveOps(values, openOptionsFrom(values), {
+        write: true,
+        ...(values.actor === 'user' || values.actor === 'agent' ? { actor: values.actor } : {}),
+    });
+    try {
+        const result = await handle.ops.write({
+            ...(values.slug ? { slug: values.slug } : {}),
+            ...(values.content !== undefined ? { content: values.content } : {}),
+            ...(values.append !== undefined ? { append: values.append } : {}),
+            ...(values.section ? { section: values.section } : {}),
+            ...(patch !== undefined ? { patch } : {}),
+            ...(values.replace !== undefined ? { replace: { find: values.replace, with: values.with } } : {}),
+            ...(event ? { event } : {}),
+            ...(values.title ? { title: values.title } : {}),
+            ...(values.type ? { type: values.type } : {}),
+            ...(values.tag ? { tags: values.tag.split(',').map((t) => t.trim()) } : {}),
+            ...(values.link ? { links: values.link.split(',').map((l) => l.trim()) } : {}),
+            ...(values.attach?.length ? { documents: values.attach.map(parseAttachment) } : {}),
+            ...(values['resolve-conflict'] ? { resolve_conflict: values['resolve-conflict'] } : {}),
+            ...(values['dry-run'] ? { dry_run: true } : {}),
+        });
+        if (values.json) {
+            json(result);
+            return result.outcome === 'ok' || result.outcome === 'noop' ? 0 : 2;
+        }
+        return printWriteOutcome(result);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * `conflict`, `requires_approval` and `requires_folder` are not failures — they are the layer
+ * doing its job, and they must reach the caller as distinguishable results. Exit code 2 marks
+ * "needs a decision", separate from 1.
+ *
+ * The three are not the same kind of thing, and the output says which. A conflict and an
+ * approval want a person; `requires_folder` wants a sentence from whoever is writing, and
+ * printing it under a heading that says "approval" is how a caller learns to wait for
+ * somebody who is never coming.
+ */
+export function printWriteOutcome(result) {
+    if (result.outcome === 'conflict' && result.conflict) {
+        const conflict = result.conflict;
+        heading(style.yellow('conflict — nothing was written'));
+        kv([
+            ['page', `${conflict.slug}:${conflict.line}`],
+            ['on file', truncate(conflict.existing, 90)],
+            ['incoming', truncate(conflict.incoming, 90)],
+        ]);
+        line(`\n  ${style.grey('ask the user which is current, then:')}`);
+        line(`  ${style.bold(`akno write … --resolve-conflict ${conflict.token}`)}`);
+        return 2;
+    }
+    if (result.outcome === 'requires_approval' && result.approval) {
+        heading(style.yellow('needs approval — nothing was written'));
+        kv([
+            ['reason', result.approval.reason],
+            ['proposal', result.approval.proposal_id],
+        ]);
+        if (result.approval.nearest.length > 0) {
+            line(`  ${style.grey('could go instead')}  ${result.approval.nearest.join(', ')}`);
+        }
+        line(`\n  ${style.bold(`akno approve ${result.approval.proposal_id}`)}  ${style.grey('or')}  ${style.bold(`akno decline ${result.approval.proposal_id}`)}`);
+        return 2;
+    }
+    if (result.outcome === 'requires_folder' && result.requires_folder) {
+        const required = result.requires_folder;
+        heading(style.yellow(`'${required.folder}' is not declared — nothing was written`));
+        if (required.nearest.length > 0) {
+            line(`  ${style.grey('could go instead')}  ${required.nearest.join(', ')}`);
+        }
+        line(`\n  ${style.grey('say what belongs there, then repeat the write:')}`);
+        line(`  ${style.bold(`akno folder ${required.folder} --description "…"`)}`);
+        return 2;
+    }
+    if (result.outcome === 'noop') {
+        line(`${statusLabel('ok')} ${style.grey(result.note ?? 'nothing changed')}`);
+        return 0;
+    }
+    line(`${statusLabel(result.status)} ${style.grey(result.change_id ? `change ${result.change_id}` : 'dry run')}`);
+    for (const target of result.wrote ?? []) {
+        const where = target.line ? `${target.slug}:${target.line}` : target.slug;
+        line(`  ${style.green(target.action.padEnd(9))} ${where}`);
+    }
+    for (const document of result.documents ?? []) {
+        // Which extractor produced the text is not a detail: a vision model's description of
+        // a photograph is not the same claim as a PDF's own text layer.
+        line(`  ${style.green('stored'.padEnd(9))} ${document.rel_path} ${document.text_from ? style.grey(`(text: ${document.text_from})`) : ''}`);
+    }
+    if (result.facts && result.facts.added > 0) {
+        line(style.grey(`  ${result.facts.added} fact(s) derived from the new lines`));
+    }
+    if (result.note)
+        line(style.grey(`  ${result.note}`));
+    return 0;
+}
+/**
+ * `path` or `path=label`. Split at the last `=` and only when the left side is a file
+ * that exists, because a path may legitimately contain one and a wrong guess would
+ * silently attach the wrong thing — or nothing.
+ */
+function parseAttachment(raw) {
+    const at = raw.lastIndexOf('=');
+    if (at > 0) {
+        const candidate = raw.slice(0, at);
+        if (fs.existsSync(candidate))
+            return { path: candidate, label: raw.slice(at + 1) };
+    }
+    return { path: raw };
+}
+function parseEvent(raw) {
+    const match = /^(\d{4}-\d{2}-\d{2})[=:]\s*(.+)$/.exec(raw.trim());
+    return match ? { date: match[1], summary: match[2] } : null;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+const REMEMBER_HELP = `akno remember [text | -] [options]
+
+  Hand over a transcript or notes and let Akno decide what is worth keeping and
+  where it goes. Use this instead of write when you do not want to choose slugs or
+  phrasing yourself. Reads stdin with '-'.
+
+  --dry-run             Show what it would keep and where, without writing.
+  --actor <who>         user | agent.
+  --json`;
+export async function rememberCommand(argv) {
+    const { values, positionals } = parse(argv, {
+        'dry-run': { type: 'boolean', default: false },
+        actor: { type: 'string' },
+    });
+    if (values.help || positionals.length === 0) {
+        line(REMEMBER_HELP);
+        return values.help ? 0 : 1;
+    }
+    const text = positionals[0] === '-' ? await readStdin() : positionals.join(' ');
+    const handle = await resolveOps(values, openOptionsFrom(values), {
+        write: true,
+        ...(values.actor === 'user' || values.actor === 'agent' ? { actor: values.actor } : {}),
+    });
+    try {
+        const result = await handle.ops.remember({
+            text,
+            ...(values['dry-run'] ? { dry_run: true } : {}),
+        });
+        if (values.json) {
+            json(result);
+            return 0;
+        }
+        // The outcome only when it says something the status does not: a successful remember
+        // printed "ok ok", which reads like a bug because it is one.
+        const outcome = result.outcome === 'ok' ? '' : ` ${style.grey(result.outcome)}`;
+        line(`${statusLabel(result.status)}${outcome}`);
+        if (result.note)
+            line(style.grey(`  ${result.note}`));
+        if (result.fallback) {
+            line(style.grey(`  fallback ${result.fallback.slug}: ${result.fallback.status === 'used'
+                ? 'selected'
+                : `unavailable (${result.fallback.reason?.replaceAll('_', ' ') ?? 'unknown reason'})`}`));
+        }
+        if (result.considered?.length) {
+            heading('Considered');
+            for (const entry of result.considered) {
+                const mark = entry.written
+                    ? style.green('wrote')
+                    : entry.kept
+                        ? style.yellow('held')
+                        : entry.destination === 'no_writable_destination'
+                            ? style.yellow('held')
+                            : style.yellow('ask ');
+                const where = entry.slug
+                    ? `${entry.slug} ${style.grey(`(${entry.score})`)}${entry.destination === 'configured_fallback' ? style.grey(' · configured fallback') : ''}`
+                    : entry.destination === 'no_writable_destination'
+                        ? style.grey('no authorized writable destination')
+                        : style.grey('no page scored high enough');
+                line(`  ${mark} ${truncate(entry.claim, 76)}`);
+                line(`       ${style.grey('→')} ${where}`);
+            }
+        }
+        if (result.wrote?.length) {
+            heading('Wrote');
+            for (const target of result.wrote) {
+                line(`  ${style.green(target.action.padEnd(9))} ${target.line ? `${target.slug}:${target.line}` : target.slug}`);
+            }
+        }
+        for (const approval of result.approvals ?? []) {
+            line(`\n${style.yellow('needs approval')} ${approval.reason}`);
+            line(`  ${style.grey('nearest')}  ${approval.nearest.join(', ')}`);
+            line(`  ${style.bold(`akno approve ${approval.proposal_id}`)}`);
+        }
+        return (result.approvals?.length ?? 0) > 0 ? 2 : 0;
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=write-cmd.js.map

package/dist/commands/write-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-cmd.js","sourceRoot":"","sources":["../../src/commands/write-cmd.ts"],"names":[],"mappings":"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"}

package/dist/ops-handle.d.ts

@@ -0,0 +1,67 @@
+import { type Akno, type MaintenanceStatus } from '@tenphi/akno-core';
+import type { CommandName, AknoOps, OpInput, OpName, OpResult } from '@tenphi/akno-protocol';
+export interface OpsHandle {
+    /**
+     * The named ops, plus the dynamic `call` both sides implement — a door that dispatches by
+     * name (MCP, HTTP) needs it, and dropping it here would force such a door to re-resolve the
+     * service itself and duplicate the fallback rules.
+     */
+    ops: AknoOps & {
+        call<N extends OpName>(op: N, input: OpInput<N>): Promise<OpResult<N>>;
+    };
+    /** Set when the ops run in-process, for commands that need more than the ops. */
+    akno: Akno | null;
+    via: 'socket' | 'in-process';
+    close(): Promise<void>;
+}
+export interface MaintenanceWaitUpdate {
+    elapsedMs: number;
+    via: 'socket' | 'in-process';
+    status: MaintenanceStatus | null;
+}
+/**
+ * Spawning a process per memory call costs 33ms against 0.04ms for a
+ * long-lived handle — an 800× difference, none of it the database. So a read
+ * command prefers a running service and only falls back to in-process, where the
+ * 33ms does not matter because there is nothing else in the process anyway.
+ *
+ * Falling back rather than failing also means the CLI works before the user has
+ * ever run `akno serve`, which is the first thing they will try.
+ *
+ * **Writes route the same way, and must.** They used to call `open()` directly, which meant every
+ * one of them failed `read_only` whenever the service was running — the arrangement the docs
+ * recommend. `akno remember` from a terminal, on a machine set up as documented, could not write.
+ */
+export declare function resolveOps(values: {
+    connect?: boolean;
+    json?: boolean;
+}, openOptions: {
+    aknoPath?: string;
+    stateDir?: string;
+}, options?: {
+    write?: boolean;
+    actor?: 'user' | 'agent' | 'akno';
+}): Promise<OpsHandle>;
+/**
+ * Runs operator work — including `index`, `inbox`, `dream`, gates, journal reads, and plans — through the
+ * running service when there
+ * is one, and in-process when there is not.
+ *
+ * Exactly one process may hold the write handle, so with a service running these have to go
+ * *through* it. They used to open the index directly and be refused, each in its own way: the
+ * nightly cycle failed with "another process holds the write handle", `index` warned and
+ * exited, and `inbox` reported an empty inbox it had never been able to read.
+ */
+export declare function runMaintenance<T>(command: CommandName, input: Record<string, unknown>, values: {
+    connect?: boolean;
+    json?: boolean;
+}, openOptions: {
+    aknoPath?: string;
+    stateDir?: string;
+}, inProcess: (akno: Akno) => Promise<T>, options?: {
+    writable?: boolean;
+    /** Periodic, content-free queue snapshots for long-running operator commands. */
+    onWait?: (update: MaintenanceWaitUpdate) => void;
+    waitEveryMs?: number;
+}): Promise<T>;
+//# sourceMappingURL=ops-handle.d.ts.map

package/dist/ops-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops-handle.d.ts","sourceRoot":"","sources":["../src/ops-handle.ts"],"names":[],"mappings":"AAGA,OAAO,EAA+B,KAAK,IAAI,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAG7F,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,GAAG,EAAE,OAAO,GAAG;QAAE,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC;IAC1F,iFAAiF;IACjF,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,GAAG,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC7B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAC7C,WAAW,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EACrD,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAA;CAAO,GACnE,OAAO,CAAC,SAAS,CAAC,CA2CpB;AAmED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAC7C,WAAW,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EACrD,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACrC,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GACL,OAAO,CAAC,CAAC,CAAC,CA+CZ"}

package/dist/ops-handle.js

@@ -0,0 +1,196 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { connect, defaultSocketPath } from '@tenphi/akno-client';
+import { AknoError, loadConfig, open } from '@tenphi/akno-core';
+import { style } from "./output.js";
+/**
+ * Spawning a process per memory call costs 33ms against 0.04ms for a
+ * long-lived handle — an 800× difference, none of it the database. So a read
+ * command prefers a running service and only falls back to in-process, where the
+ * 33ms does not matter because there is nothing else in the process anyway.
+ *
+ * Falling back rather than failing also means the CLI works before the user has
+ * ever run `akno serve`, which is the first thing they will try.
+ *
+ * **Writes route the same way, and must.** They used to call `open()` directly, which meant every
+ * one of them failed `read_only` whenever the service was running — the arrangement the docs
+ * recommend. `akno remember` from a terminal, on a machine set up as documented, could not write.
+ */
+export async function resolveOps(values, openOptions, options = {}) {
+    const target = serviceTarget(values, openOptions);
+    const socketPath = target.socketPath;
+    if (values.connect || fs.existsSync(socketPath)) {
+        try {
+            const client = await connectToTarget(target, {
+                // Stated per connection, because the alternative is a write from a person at a terminal
+                // being gated as though an agent had asked — and a gated proposal being unanswerable
+                // through the door the service is meant to be reached by.
+                ...(options.actor ? { actor: options.actor } : {}),
+            });
+            return {
+                ops: client,
+                akno: null,
+                via: 'socket',
+                close: () => client.close(),
+            };
+        }
+        catch (err) {
+            const error = AknoError.from(err);
+            if (values.connect || error.code !== 'unavailable')
+                throw error;
+            // A stale socket file from a crashed service is common enough that
+            // failing here would be a bad default.
+            if (!values.json) {
+                process.stderr.write(style.grey(`no service on ${socketPath}; opening the index in-process\n`));
+            }
+        }
+    }
+    // A read takes no write handle: a one-shot must never pull it out from under a service that is
+    // about to start, and it does not need it. A write has no choice — with no service there is
+    // nobody else to do it.
+    const akno = await open({
+        ...openOptions,
+        writable: options.write === true,
+        ...(options.actor ? { actor: options.actor } : {}),
+    });
+    return {
+        ops: akno,
+        akno,
+        via: 'in-process',
+        close: () => akno.close(),
+    };
+}
+function serviceTarget(values, openOptions) {
+    try {
+        const config = loadConfig(openOptions);
+        return { socketPath: config.socketPath, expectedAknoPath: config.aknoPath };
+    }
+    catch (error) {
+        // `--connect` without a memory/config override is an explicit request for the conventional
+        // service door. Every implicit or targeted call must retain the configuration error instead
+        // of using that door and accidentally operating on whichever knowledge base is already live.
+        if (values.connect && !hasExplicitMemoryTarget(openOptions)) {
+            return { socketPath: defaultSocketPath(), expectedAknoPath: null };
+        }
+        throw error;
+    }
+}
+function hasExplicitMemoryTarget(openOptions) {
+    return Boolean(openOptions.aknoPath ||
+        openOptions.stateDir ||
+        process.env.AKNO_CONFIG ||
+        process.env.AKNO_PATH ||
+        process.env.AKNO_STATE_DIR);
+}
+async function connectToTarget(target, options = {}) {
+    const client = await connect({ socket: target.socketPath, ...options });
+    try {
+        if (target.expectedAknoPath &&
+            pathIdentity(client.hello.akno_path) !== pathIdentity(target.expectedAknoPath)) {
+            throw new AknoError('conflict', `the service on ${target.socketPath} is for ${client.hello.akno_path}, not ` +
+                `${target.expectedAknoPath}; use a matching --state-dir for the requested knowledge base`, { reason: 'service_target_mismatch' });
+        }
+        return client;
+    }
+    catch (error) {
+        await client.close().catch(() => { });
+        throw error;
+    }
+}
+function pathIdentity(value) {
+    try {
+        return fs.realpathSync.native(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+/**
+ * Runs operator work — including `index`, `inbox`, `dream`, gates, journal reads, and plans — through the
+ * running service when there
+ * is one, and in-process when there is not.
+ *
+ * Exactly one process may hold the write handle, so with a service running these have to go
+ * *through* it. They used to open the index directly and be refused, each in its own way: the
+ * nightly cycle failed with "another process holds the write handle", `index` warned and
+ * exited, and `inbox` reported an empty inbox it had never been able to read.
+ */
+export async function runMaintenance(command, input, values, openOptions, inProcess, options = {}) {
+    const target = serviceTarget(values, openOptions);
+    const socketPath = target.socketPath;
+    if (values.connect || fs.existsSync(socketPath)) {
+        try {
+            const client = await connectToTarget(target);
+            try {
+                if (!values.json) {
+                    process.stderr.write(style.grey(`via the service on ${socketPath}\n`));
+                }
+                return await withWaitUpdates(client.command(command, input), 'socket', async () => (await client.command('plan', { action: 'status' })), options);
+            }
+            finally {
+                await client.close();
+            }
+        }
+        catch (err) {
+            const error = AknoError.from(err);
+            // A command error came from a healthy service and must reach its caller intact. Falling
+            // back here used to turn a precise refusal into a second, misleading in-process attempt.
+            if (error.code !== 'unavailable')
+                throw error;
+            // `--connect` means the caller wants the service or nothing; otherwise a stale socket
+            // file from a crashed service must not stop a one-off pass.
+            if (values.connect)
+                throw error;
+            if (!values.json) {
+                process.stderr.write(style.grey(`no service on ${socketPath}; running in-process\n`));
+            }
+        }
+    }
+    // Proposal, change, and plan reads only inspect state; taking the write handle for them would block a service
+    // from starting while somebody lists their pending approvals.
+    const akno = await open({ ...openOptions, ...(options.writable === false ? { writable: false } : {}) });
+    try {
+        return await withWaitUpdates(inProcess(akno), 'in-process', async () => akno.maintenanceStatus(), options);
+    }
+    finally {
+        await akno.close();
+    }
+}
+async function withWaitUpdates(work, via, readStatus, options) {
+    if (!options.onWait)
+        return work;
+    const started = performance.now();
+    const every = Math.max(1_000, options.waitEveryMs ?? 5_000);
+    let stopped = false;
+    let timer = null;
+    let polling = false;
+    const emit = async () => {
+        if (stopped || polling)
+            return;
+        polling = true;
+        let status = null;
+        try {
+            status = await readStatus();
+        }
+        catch {
+            // Progress is observational. Losing one snapshot must never fail or cancel the work.
+        }
+        finally {
+            polling = false;
+        }
+        if (!stopped) {
+            options.onWait?.({ elapsedMs: Math.round(performance.now() - started), via, status });
+            timer = setTimeout(() => void emit(), every);
+        }
+    };
+    timer = setTimeout(() => void emit(), every);
+    try {
+        return await work;
+    }
+    finally {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=ops-handle.js.map

package/dist/ops-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops-handle.js","sourceRoot":"","sources":["../src/ops-handle.ts"],"names":[],"mappings":"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"}

package/dist/output.d.ts

@@ -0,0 +1,28 @@
+export declare const style: {
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    red: (text: string) => string;
+    green: (text: string) => string;
+    yellow: (text: string) => string;
+    blue: (text: string) => string;
+    cyan: (text: string) => string;
+    grey: (text: string) => string;
+};
+export declare function heading(text: string): void;
+export declare function line(text?: string): void;
+export declare function json(value: unknown): void;
+export declare function fail(message: string): void;
+export declare function warn(message: string): void;
+/** Aligned key/value block. `-` in the value column reads better than empty. */
+export declare function kv(entries: [string, string | number | null | undefined][], indent?: string): void;
+/**
+ * A status is not decoration — `empty` and `unavailable` mean different things
+ * to the caller, and the colour is there so a human scanning output does not have
+ * to read the word to notice which one happened.
+ */
+export declare function statusLabel(status: string): string;
+/** In-place progress on a TTY; one line per phase otherwise, so logs stay readable. */
+export declare function progressWriter(): (phase: string, done: number, total: number, detail?: string) => void;
+export declare function truncate(text: string, max: number): string;
+export declare function ms(value: number): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,KAAK;iBAJoB,MAAM,KAAK,MAAM;gBAAjB,MAAM,KAAK,MAAM;gBAAjB,MAAM,KAAK,MAAM;kBAAjB,MAAM,KAAK,MAAM;mBAAjB,MAAM,KAAK,MAAM;iBAAjB,MAAM,KAAK,MAAM;iBAAjB,MAAM,KAAK,MAAM;iBAAjB,MAAM,KAAK,MAAM;CAatD,CAAC;AAEF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,wBAAgB,IAAI,CAAC,IAAI,SAAK,GAAG,IAAI,CAEpC;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEzC;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,gFAAgF;AAChF,wBAAgB,EAAE,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,MAAM,SAAO,GAAG,IAAI,CAK/F;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAclD;AAED,uFAAuF;AACvF,wBAAgB,cAAc,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAgBtG;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxC"}