noggin-cli 0.1.3 → 0.4.3

package/noggin-api.d.mts

@@ -1,19 +1,34 @@
 // Type declarations for noggin-api.mjs.
 //
 // Hand-written to match the JS implementation; no build step. The .mjs uses
-// /// <reference path="./noggin-api.d.ts" /> so editors and tsc --noEmit can
+// /// <reference path="./noggin-api.d.mts" /> so editors and tsc --noEmit can
 // check usages against this contract.
+//
+// API stability tiers (TSDoc release tags):
+//   @public      — Stable contract. Breaking changes require a major bump.
+//   @experimental — Public but the shape may still change.
+//   @internal    — Implementation detail; do not depend on this.
+
+// ── Core identifiers ─────────────────────────────────────────────────────────
 
-export type NogginFilePath = string;
+/** @public Opaque, stable item identifier. Treat as a string token. */
 export type ItemKey = string;
+
+/** @public Tree path string (e.g. `/1/2/3` or `./X`). Display coordinate only. */
 export type ItemPath = string;
+
+/** @public ISO-8601 / RFC 3339 date-time string. */
 export type IsoTimestamp = string;
 
+// ── Data model ───────────────────────────────────────────────────────────────
+
+/** @public A single entry in an item's append-only note log. */
 export interface Note {
   timestamp: IsoTimestamp;
   text: string;
 }
 
+/** @public A single work item in the noggin tree. */
 export interface Item {
   key: ItemKey;
   parentKey: ItemKey | null;
@@ -23,102 +38,76 @@ export interface Item {
   notes: Note[];
 }
 
-export interface Store {
+/**
+ * @public
+ * The serialized form of a noggin: pure data. The JSON Schema validates
+ * this shape; serializers convert it to/from YAML or JSON; backends
+ * load and save it.
+ */
+export interface NogginDocument {
   schemaVersion: number;
   active: ItemKey | null;
   items: Item[];
 }
 
-/** An Item enriched with computed path and 1-based sibling position. */
+/** @public An Item enriched with computed path and 1-based sibling position. */
 export interface ItemView extends Item {
   path: ItemPath | null;
   position: number | null;
 }
 
-/**
- * A node in a CurrentTreeView's recursive tree. Carries the usual
- * ItemView fields plus an *optional* `children` slot:
- *
- *   children present  this view renders this node's child level (the
- *                     array may be empty — e.g. target with no kids)
- *   children absent   leaf of this view; the store may have a subtree
- *                     here, but this view doesn't render it
- *
- * The recursion walks the direct ancestor chain from root to target.
- * Each ancestor has a single-element `children`. The target's parent
- * has the full peer row. The target has `children` populated with its
- * first-level kids (or no `children` field at all with `--nokids`).
- * Peers and grandkids are leaves and have no `children` field.
- */
+/** @public A node in a CurrentTreeView's recursive tree. */
 export interface ViewNode extends ItemView {
   children?: ViewNode[];
 }
 
-/** Shape returned by every mutating verb and by `show`/`view`. */
+/** @public Shape returned by every mutating verb and by `verbs.show`. */
 export interface CurrentTreeView {
-  /** Path of the active item, or null. May differ from the target —
-   *  active is the user's persistent cursor (📍) and is not necessarily
-   *  on the spine of this view. */
   activePath: ItemPath | null;
-  /** Stable key of the active item, or null. */
   activeKey: ItemKey | null;
-  /** Stable key of the item the verb acted on. To grab the full row,
-   *  walk `items` and find the node whose `key === targetKey`. */
   targetKey: ItemKey;
-  /**
-   * Top of the rendered tree. Contains either:
-   *   - a single root ancestor (when the target is below depth 0); or
-   *   - the target's full peer row (when the target itself is a root).
-   * Either way, every node along the path from `items` down to the
-   * target has a non-null `children`; leaves of the view have `null`.
-   */
   items: ViewNode[];
 }
 
-/** Identifying tombstone for a deleted item — survives the delete itself. */
+/** @public Identifying tombstone for a deleted item. */
 export interface DeletedItem {
   key: ItemKey;
   path: ItemPath | null;
   title: string;
 }
 
+/** @public */
 export type PlacementKind = 'before' | 'after' | 'into';
 
+/** @public Placement spec for `add` / `move`. */
 export interface Placement {
   kind: PlacementKind;
-  /** Path to the anchor item. Resolved against the live store. */
+  /** Path to the anchor item. */
   anchor: ItemPath;
 }
 
-/** Optional reposition-after-write. Mirrors the CLI `--goto` flag. */
+/** @public Optional reposition-after-write. Mirrors the CLI `--goto` flag. */
 export interface GotoOption {
-  /**
-   * Path resolved relative to the operation's target.
-   * `true` (or omitted with bare `--goto`) means `.` (the target itself).
-   */
+  /** Path resolved relative to the operation's target. `true` means `.`. */
   goto?: ItemPath | true;
 }
 
-export interface FileResolution {
-  file: NogginFilePath;
-  source: 'flag' | 'env' | 'default';
-  exists: boolean;
-  defaultFile: NogginFilePath;
-  /** Value of $NOGGIN_FILE at the time of resolution, or null. */
-  env: string | null;
-}
-
+/** @public Result of `verbs.delete`. */
 export interface DeleteResult {
   deleted: DeletedItem;
   descendantCount: number;
-  /** Null only when the resulting tree has no active item (e.g. a root was deleted). */
   view: CurrentTreeView | null;
 }
 
+// ── Errors ───────────────────────────────────────────────────────────────────
+
+/** @public Closed-ish union of error codes. New codes are non-breaking. */
 export type NogginErrorCode =
   | 'noggin-error'
   | 'no-active-item'
   | 'no-file'
+  | 'no-location'
+  | 'no-factory'
   | 'path-not-found'
   | 'path-required'
   | 'cycle'
@@ -136,10 +125,13 @@ export type NogginErrorCode =
   | 'open-descendants'
   | 'pop-no-path'
   | 'invalid-note'
-  | 'invalid-store'
+  | 'invalid-op'
+  | 'invalid-document'
   | 'unsupported-schema'
+  | 'lock-timeout'
   | 'io';
 
+/** @public Thrown by every engine function on usage/state errors. */
 export class NogginError extends Error {
   readonly code: NogginErrorCode | string;
   /** Mirrors the CLI exit code (1 = runtime/state, 2 = usage/parse/invalid). */
@@ -149,169 +141,280 @@ export class NogginError extends Error {
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
+/** @public Current `schemaVersion` written into a `NogginDocument`. */
 export const SCHEMA_VERSION: number;
-export const JSON_SCHEMA_VERSION: number;
-export const DEFAULT_FILE: NogginFilePath;
 
-// ── Stateless functions ──────────────────────────────────────────────────────
+/** @public Current `envelopeVersion` stamped onto every response envelope. */
+export const RESPONSE_ENVELOPE_VERSION: number;
 
-export function resolveFile(opts?: { file?: NogginFilePath; env?: Record<string, string | undefined> }): FileResolution;
+/** @public @deprecated Renamed to `RESPONSE_ENVELOPE_VERSION`. */
+export const JSON_SCHEMA_VERSION: number;
 
-export function loadStore(file: NogginFilePath): Store;
-export function saveStore(file: NogginFilePath, store: Store): void;
+/** @public The system-generated note text appended on close. */
+export const CLOSE_NOTE_TEXT: string;
 
-export function resolvePath(store: Store, path: ItemPath): Item;
-export function tryResolvePath(store: Store, path: ItemPath): Item | null;
+// ── Eventing primitives ─────────────────────────────────────────────────────
 
-export function pathOf(store: Store, item: Item | null | undefined): ItemPath | null;
-export function childrenOf(store: Store, parentKey: ItemKey | null | undefined): Item[];
+/** @public Disposable returned by event subscriptions. */
+export interface Disposable { dispose(): void }
 
-export function buildView(
-  store: Store,
-  target: Item,
-  opts?: { includeChildren?: boolean; withSiblings?: boolean; withDescendants?: boolean }
-): CurrentTreeView;
+/** @public vscode-style event subscribe function. */
+export type Event<T> = (handler: (e: T) => void) => Disposable;
 
-// ── JSON envelope ────────────────────────────────────────────────────────────
+// ── Noggin (interface) ──────────────────────────────────────────────────────
 
 /**
- * Canonical JSON envelope shared by the CLI `--json` output and the VS
- * Code extension's language-model tools. Both surfaces emit this exact
- * shape so a single consumer (or test) can target both.
+ * @public
+ * A live noggin. Backends implement this interface; consumers consume
+ * it. Read accessors are synchronous and reflect the current state.
+ * `apply(ops)` is the only mutator — every backend implements it; the
+ * `verbs` namespace composes ops and calls it.
+ *
+ * Storage-tracking contract:
+ *   - Accessors always reflect the latest known state.
+ *   - `onDidChange` fires after every mutation (in-process or externally
+ *     observed). After it fires, accessors are up to date.
  */
-export interface SuccessEnvelope<T = unknown> {
-  status: 'ok';
-  schemaVersion: number;
-  verb: string | null;
-  file: NogginFilePath | null;
-  data: T;
-}
+export interface Noggin {
+  // accessors (sync)
+  readonly items: readonly Item[];
+  readonly active: Item | null;
+  readonly roots: readonly Item[];
 
-export interface ErrorEnvelope {
-  status: 'error';
-  schemaVersion: number;
-  verb: string | null;
-  file: NogginFilePath | null;
-  error: {
-    code: NogginErrorCode | string;
-    message: string;
-    exitCode: number;
-  };
+  findByKey(k: ItemKey | null | undefined): Item | null;
+  childrenOf(k: ItemKey | null | undefined): readonly Item[];
+  pathOf(item: Item | null | undefined): ItemPath | null;
+  resolvePath(p: ItemPath): Item;
+  tryResolvePath(p: ItemPath): Item | null;
+
+  /** Atomically apply a list of `AtomicOp`s. The only write primitive. */
+  apply(ops: readonly AtomicOp[]): Promise<void>;
+
+  /** Release backend resources. After dispose the noggin is unusable. */
+  dispose(): Promise<void>;
+
+  /** Human-readable description of where this noggin lives. Not machine-parseable. */
+  describe(): string;
+
+  readonly onDidChange: Event<void>;
+  readonly onDidError: Event<NogginError>;
 }
 
-export type JsonEnvelope<T = unknown> = SuccessEnvelope<T> | ErrorEnvelope;
+// ── Atomic ops ──────────────────────────────────────────────────────────────
+
+/**
+ * @public
+ * Atomic state mutations. Every change to a noggin's state goes through
+ * one of these. Verbs compose op lists; backends execute them
+ * atomically via `Noggin.apply(ops)`.
+ *
+ * `position` is the 0-based index among siblings of `parentKey`, or
+ * the literal string `'end'` to append.
+ */
+export type AtomicOp =
+  | { type: 'add'; item: Item; parentKey: ItemKey | null; position: number | 'end' }
+  | { type: 'remove'; keys: readonly ItemKey[] }
+  | { type: 'set'; key: ItemKey; patch: { title?: string; done?: boolean } }
+  | { type: 'note'; key: ItemKey; note: Note }
+  | { type: 'move'; key: ItemKey; parentKey: ItemKey | null; position: number | 'end' }
+  | { type: 'setActive'; key: ItemKey | null };
+
+/**
+ * @public
+ * Apply a list of `AtomicOp`s to a `NogginDocument` in-place, then
+ * validate. Used by backends inside their `apply()`; also useful for
+ * offline document manipulation. Throws `NogginError` if any op
+ * references missing data or the resulting document is malformed.
+ */
+export function applyOps(doc: NogginDocument, ops: readonly AtomicOp[]): NogginDocument;
 
-export function formatSuccess<T>(opts: {
-  verb?: string;
-  file?: NogginFilePath | null;
-  data?: T;
-}): SuccessEnvelope<T>;
+/**
+ * @public
+ * Validate a document's structural invariants. Throws `NogginError`
+ * with code `'invalid-document'` on failure.
+ */
+export function validateDocument(doc: NogginDocument): void;
+
+/**
+ * @public
+ * Normalize a parsed document in-place: stamp schemaVersion, normalize
+ * notes, strip legacy fields.
+ */
+export function normalizeDocument(doc: NogginDocument): NogginDocument;
+
+/** @internal Used by serializers and `applyOps`. */
+export function normalizeNote(note: { timestamp?: string | null; text: string }): Note;
+
+/**
+ * @public
+ * Structural equality between two documents. Used by backends to
+ * decide whether an external change actually changed anything.
+ */
+export function documentsEqual(a: NogginDocument, b: NogginDocument): boolean;
 
-export function formatError(opts: {
-  verb?: string;
-  file?: NogginFilePath | null;
-  error: unknown;
-}): ErrorEnvelope;
+/**
+ * @public
+ * Deep-freeze a document so accessors can return references without
+ * worrying about consumer mutation.
+ */
+export function freezeDocument(doc: NogginDocument): NogginDocument;
 
-// ── Verb functions (stateless) ───────────────────────────────────────────────
+// ── Verbs ───────────────────────────────────────────────────────────────────
 
+/** @public Optional context for verbs that stamp timestamps. */
+export interface VerbContext {
+  /** Fixed clock for deterministic timestamps in tests. */
+  now?: Date;
+}
+
+/** @public */
 export interface PushOptions { title: string }
+/** @public */
 export interface AddOptions extends GotoOption { title: string; placement?: Placement }
+/** @public */
 export interface MoveOptions extends GotoOption { path?: ItemPath; placement: Placement }
-export interface GotoOptions { path?: ItemPath }
+/** @public */
+export interface GotoOptions { path: ItemPath }
 
-/** Shared shape for closing verbs (`done`, `pop`, `set --done`). */
+/** @public Shared shape for closing verbs (`done`, `pop`, `edit --done`). */
 export interface CloseOptions {
-  /** Skip the open-descendant safety check; close the target even with open kids. */
   force?: boolean;
-  /** Close every open descendant first (each gets its own system close note). */
   closeAll?: boolean;
 }
 
+/** @public */
 export interface DoneOptions extends CloseOptions { path?: ItemPath }
+/** @public */
 export interface PopOptions extends CloseOptions {}
 
-/**
- * `edit` combines the old `set-state` and `retitle` verbs into one
- * idempotent mutation verb. Specify at least one of `done`/`title`;
- * each operation is a no-op when the value already matches.
- */
+/** @public */
 export interface EditOptions extends GotoOption, CloseOptions {
   path?: ItemPath;
-  /** true → close, false → reopen, undefined → don't touch state. */
   done?: boolean;
-  /** New title (trimmed). Empty/whitespace is ignored, not an error. */
   title?: string;
 }
 
+/** @public */
 export interface ShowOptions extends GotoOption {
   path?: ItemPath;
-  /** Whether to expand the target's `children` field. Default true; set false for --no-children. */
   includeChildren?: boolean;
-  /** Show note bodies in human output (no effect on JSON — notes are always present). */
   withNotes?: boolean;
-  /** Include the full sibling row at every ancestor depth. */
   withSiblings?: boolean;
-  /** Expand the target's subtree recursively. */
   withDescendants?: boolean;
 }
+/** @public */
 export interface NoteOptions extends GotoOption { path?: ItemPath; text: string }
+/** @public */
 export interface DeleteOptions { path: ItemPath; recursive?: boolean }
 
-export function apiPush(file: NogginFilePath, opts: PushOptions): CurrentTreeView;
-export function apiAdd(file: NogginFilePath, opts: AddOptions): CurrentTreeView;
-export function apiMove(file: NogginFilePath, opts: MoveOptions): CurrentTreeView;
-export function apiGoto(file: NogginFilePath, opts: GotoOptions): CurrentTreeView;
-export function apiDone(file: NogginFilePath, opts?: DoneOptions): CurrentTreeView;
-export function apiPop(file: NogginFilePath, opts?: PopOptions): CurrentTreeView;
-export function apiEdit(file: NogginFilePath, opts: EditOptions): CurrentTreeView;
-export function apiShow(file: NogginFilePath, opts?: ShowOptions): CurrentTreeView | null;
-export function apiNote(file: NogginFilePath, opts: NoteOptions): CurrentTreeView;
-export function apiDelete(file: NogginFilePath, opts: DeleteOptions): DeleteResult;
-export function apiWhere(opts?: { file?: NogginFilePath; env?: Record<string, string | undefined> }): FileResolution;
+/**
+ * @public
+ * The single verb implementation, shared by every backend. Each verb
+ * reads state via the `Noggin`'s accessors, composes an `AtomicOp[]`,
+ * calls `noggin.apply(ops)` once, and returns the resulting view (or
+ * a `DeleteResult` for delete).
+ *
+ * Verb behavior contracts (push moves active, add doesn't, done
+ * appends a close note and surfaces to parent, etc.) live here.
+ * Backends do not implement verbs.
+ */
+export const verbs: {
+  push(noggin: Noggin, opts: PushOptions, ctx?: VerbContext): Promise<CurrentTreeView>;
+  add(noggin: Noggin, opts: AddOptions, ctx?: VerbContext): Promise<CurrentTreeView>;
+  move(noggin: Noggin, opts: MoveOptions): Promise<CurrentTreeView>;
+  goto(noggin: Noggin, opts: GotoOptions): Promise<CurrentTreeView>;
+  done(noggin: Noggin, opts?: DoneOptions, ctx?: VerbContext): Promise<CurrentTreeView>;
+  pop(noggin: Noggin, opts?: PopOptions, ctx?: VerbContext): Promise<CurrentTreeView>;
+  edit(noggin: Noggin, opts: EditOptions, ctx?: VerbContext): Promise<CurrentTreeView>;
+  show(noggin: Noggin, opts?: ShowOptions): Promise<CurrentTreeView | null>;
+  note(noggin: Noggin, opts: NoteOptions, ctx?: VerbContext): Promise<CurrentTreeView>;
+  delete(noggin: Noggin, opts: DeleteOptions): Promise<DeleteResult>;
+};
+
+// ── Factory registry ───────────────────────────────────────────────────────
+
+/** @public A backend factory: claims a scheme prefix, opens a Noggin. */
+export interface NogginFactory {
+  readonly scheme: string;
+  open(location: string, opts?: object): Promise<Noggin>;
+}
 
-// ── Noggin class ─────────────────────────────────────────────────────────────
+/** @public Registry interface. The exported `factories` is the singleton. */
+export interface NogginFactoryRegistry {
+  register(factory: NogginFactory, opts?: { default?: boolean }): void;
+  unregister(scheme: string): boolean;
+  get(scheme: string): NogginFactory | null;
+  getDefault(): NogginFactory | null;
+  list(): readonly { scheme: string; default: boolean }[];
+}
 
-export interface Disposable { dispose(): void }
-export type Event<T> = (handler: (e: T) => void) => Disposable;
+/** @public The process-wide noggin factory registry. */
+export const factories: NogginFactoryRegistry;
 
-export class Noggin {
-  constructor(file: NogginFilePath, opts?: { watch?: boolean });
+/**
+ * @public
+ * Open a noggin by location. The scheme prefix (e.g. `file://`,
+ * `localstorage://`) selects the factory; a bare location goes to
+ * whichever factory was registered with `{default: true}`.
+ */
+export function openNoggin(location: string, opts?: object): Promise<Noggin>;
 
-  readonly file: NogginFilePath;
+// ── Public utilities ────────────────────────────────────────────────────────
 
-  readonly store: Readonly<Store>;
-  readonly active: Item | null;
-  readonly roots: Item[];
+/**
+ * @public
+ * Resolve a path string against a doc-shaped `{items, active}` snapshot.
+ * Throws `NogginError('path-not-found')` if the path doesn't resolve.
+ */
+export function resolvePath(snapshot: { items: Item[]; active: ItemKey | null }, p: ItemPath): Item;
 
-  findByKey(key: ItemKey | null | undefined): Item | null;
-  childrenOf(parentKey: ItemKey | null | undefined): Item[];
-  pathOf(item: Item | null | undefined): ItemPath | null;
-  resolvePath(path: ItemPath): Item;
-  tryResolvePath(path: ItemPath): Item | null;
+/** @public Like `resolvePath` but returns `null` instead of throwing. */
+export function tryResolvePath(snapshot: { items: Item[]; active: ItemKey | null }, p: ItemPath): Item | null;
 
-  view(
-    target?: Item | ItemPath | null,
-    opts?: { includeChildren?: boolean }
-  ): CurrentTreeView | null;
+/** @public Compute the absolute path string for an item. */
+export function pathOf(snapshot: { items: Item[] }, item: Item | null | undefined): ItemPath | null;
 
-  reload(): boolean;
-  dispose(): void;
+/** @public Direct children of `parentKey` (null = roots), in tree order. */
+export function childrenOf(snapshot: { items: Item[] }, parentKey: ItemKey | null | undefined): Item[];
 
-  readonly onDidChange: Event<void>;
-  readonly onDidError: Event<NogginError>;
+/**
+ * @public
+ * Build a CurrentTreeView for `target`. Pure; does not mutate.
+ * Accepts a noggin or a `{items, active}` doc-shape.
+ */
+export function buildView(
+  snapshot: { items: readonly Item[]; active: ItemKey | null },
+  target: Item,
+  opts?: { includeChildren?: boolean; withSiblings?: boolean; withDescendants?: boolean }
+): CurrentTreeView;
 
-  push(opts: PushOptions): CurrentTreeView;
-  add(opts: AddOptions): CurrentTreeView;
-  move(opts: MoveOptions): CurrentTreeView;
-  goto(path: ItemPath): CurrentTreeView;
-  done(opts?: DoneOptions): CurrentTreeView;
-  pop(opts?: PopOptions): CurrentTreeView;
-  edit(opts: EditOptions): CurrentTreeView;
-  show(opts?: ShowOptions): CurrentTreeView | null;
-  note(opts: NoteOptions): CurrentTreeView;
-  delete(opts: DeleteOptions): DeleteResult;
-  where(): FileResolution;
+// ── Response envelope ───────────────────────────────────────────────────────
+
+/** @public */
+export interface SuccessEnvelope<T = unknown> {
+  status: 'ok';
+  envelopeVersion: number;
+  verb: string | null;
+  data: T;
 }
 
-export function openNoggin(file: NogginFilePath): Noggin;
+/** @public */
+export interface ErrorEnvelope {
+  status: 'error';
+  envelopeVersion: number;
+  verb: string | null;
+  error: {
+    code: NogginErrorCode | string;
+    message: string;
+    exitCode: number;
+  };
+}
+
+/** @public */
+export type JsonEnvelope<T = unknown> = SuccessEnvelope<T> | ErrorEnvelope;
+
+/** @public */
+export function formatSuccess<T>(opts: { verb?: string; data?: T }): SuccessEnvelope<T>;
+
+/** @public */
+export function formatError(opts: { verb?: string; error: unknown }): ErrorEnvelope;