@astrosheep/pi-context 0.25.1 → 0.26.0

package/dist/src/notes/store.d.ts

@@ -0,0 +1,94 @@
+import { type NotesContext } from "./context.js";
+import { type NoteMeta, type NoteStatus, type Origin } from "./frontmatter.js";
+import { type Scope } from "./paths.js";
+export type { NoteMeta, NoteStatus, Origin, Scope };
+export type NoteErrorCode = "not_found" | "ambiguous_edit" | "no_match" | "nothing_to_do" | "too_large" | "invalid_scope" | "invalid_origin";
+/** Typed store refusal. Edit locations are exposed in camelCase. */
+export declare class NoteError extends Error {
+    readonly code: NoteErrorCode;
+    readonly lineNumbers?: number[];
+    readonly editIndex?: number;
+    constructor(code: NoteErrorCode, message: string, extra?: {
+        lineNumbers?: number[];
+        editIndex?: number;
+    });
+}
+export type NoteRow = {
+    address: string;
+    scope: Scope;
+    path: string;
+    meta: NoteMeta;
+    body: string;
+    sizeBytes: number;
+};
+export type NoteMatch = {
+    line: number;
+    text: string;
+    offsetChars: number;
+};
+export type NoteSearchRow = {
+    address: string;
+    scope: Scope;
+    path: string;
+    meta: NoteMeta;
+    matches: NoteMatch[];
+};
+export type EditOperation = {
+    oldText: string;
+    newText: string;
+};
+export type WriteOptions = {
+    origin?: Origin;
+    stale?: boolean;
+};
+export type EditOptions = {
+    origin?: Origin;
+    stale?: boolean;
+    replaceAll?: boolean;
+};
+export type NotesQuery = ({
+    scope?: undefined;
+    who?: never;
+} | {
+    scope: "session" | "project" | "human";
+    who?: never;
+} | {
+    scope: "agent" | "model";
+    who?: string;
+}) & {
+    pattern?: string;
+};
+export type NoteReadResult = {
+    meta: NoteMeta;
+    body: string;
+    text: string;
+    resolvedScope: Scope;
+};
+export type NoteWriteResult = {
+    meta: NoteMeta;
+};
+export type NoteChange = {
+    kind: "none";
+    before: "";
+    after: "";
+} | {
+    kind: "body" | "metadata" | "file";
+    before: string;
+    after: string;
+};
+export type NoteEditResult = {
+    meta: NoteMeta;
+    applied: number;
+    resolvedScope: Scope;
+    change: NoteChange;
+};
+/** Host-neutral, filesystem-backed notes API. */
+export interface NotesStore {
+    write(address: string, content: string, options?: WriteOptions): Promise<NoteWriteResult>;
+    read(address: string): Promise<NoteReadResult | undefined>;
+    edit(address: string, edits?: EditOperation[], options?: EditOptions): Promise<NoteEditResult>;
+    list(options?: NotesQuery): Promise<NoteRow[]>;
+    search(queries: string[], options?: NotesQuery): Promise<NoteSearchRow[]>;
+}
+/** Create a store over one validated, immutable snapshot of the supplied explicit identity. */
+export declare function createNotesStore(input: NotesContext): NotesStore;