orbitmap 0.3.0 → 0.4.1

package/dist/adapters/local/store.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Local file store (spec §4).
+ *
+ * All file I/O for local mode lives here: frontmatter+body parsing, atomic writes,
+ * advisory locking, the workspace scaffold, entity-number counters and lookups.
+ * It knows nothing about the Agent API envelopes (that is `shapes.ts`) and nothing
+ * about domain validation (that is `rules.ts`).
+ *
+ * Everything is async and every path is built with `node:path`, so the store behaves
+ * identically on Windows and POSIX.
+ */
+import { type AreaFile, type DocumentRecord, type EntityKind, type FoundEntity, type LocalFile, type LocalRecord, type RecordFor, type WorkspaceCounters, type WorkspaceFile } from './types.js';
+/** Unexpected/corrupt state on disk (unreadable file, bad frontmatter, failed write). */
+export declare const LOCAL_STORE_ERROR = "LOCAL_STORE_ERROR";
+/** The advisory lock could not be acquired within the retry budget. */
+export declare const LOCK_TIMEOUT = "LOCK_TIMEOUT";
+/** A referenced entity/area/document does not exist on disk. */
+export declare const NOT_FOUND = "NOT_FOUND";
+export declare const WORKSPACE_FILE_NAME = "workspace.yml";
+export declare const AREA_FILE_NAME = "area.yml";
+export declare const LOCK_FILE_NAME = ".lock";
+export declare const AREAS_DIR = "areas";
+export declare const DOCUMENTS_DIR = "documents";
+/** Workspace-level directories created by the scaffold. */
+export declare const WORKSPACE_DIRS: readonly ["missions", "intents", "ideas", "documents", "issues"];
+/** Per-area directories created by the scaffold. */
+export declare const AREA_DIRS: readonly ["tasks", "issues", "vibes"];
+/**
+ * Split a Markdown file into its YAML frontmatter object and its body.
+ *
+ * The delimiter is `---` on line 1. The *whole* YAML mapping is returned, so unknown
+ * keys survive a read → modify → write round trip.
+ */
+export declare function parseFrontmatter<T extends LocalRecord = LocalRecord>(raw: string, source?: string): {
+    frontmatter: T;
+    body: string;
+};
+/** Render a frontmatter object + body back into a Markdown file. */
+export declare function serialiseFrontmatter(frontmatter: LocalRecord, body?: string): string;
+/** `prefix + '-' + counter.toString(36).padStart(6, '0')`, e.g. `TS-000001`. */
+export declare function formatEntityNumber(kind: EntityKind, counter: number): string;
+/** The entity kind an entity number belongs to, or `undefined` if not a number. */
+export declare function kindOfEntityNumber(ref: string): EntityKind | undefined;
+/** True when `ref` looks like `TS-…`/`IS-…`/… rather than a uuid or slug. */
+export declare function isEntityNumber(ref: string): boolean;
+export interface LocalStoreOptions {
+    /** Lock acquisition attempts before failing. Default 10 (spec §4.12). */
+    lockRetries?: number;
+    /** Delay between lock attempts, in ms. Default 100 (spec §4.12). */
+    lockRetryDelayMs?: number;
+}
+export interface ScaffoldOptions {
+    /** Workspace display name. */
+    name: string;
+    /** Workspace slug. Defaults to a slugified `name`. */
+    slug?: string;
+    description?: string;
+    /** Pre-generated workspace uuid (mainly for tests). */
+    workspaceId?: string;
+    /** Optional first area created alongside the workspace. */
+    area?: CreateAreaInput;
+}
+export interface CreateAreaInput {
+    name: string;
+    slug?: string;
+    description?: string;
+    gitUrl?: string | null;
+    defaultBranch?: string;
+    agentInstructionsTemplate?: string | null;
+    areaId?: string;
+}
+export declare class LocalStore {
+    /** Absolute path of the workspace root directory. */
+    readonly root: string;
+    private readonly lockRetries;
+    private readonly lockRetryDelayMs;
+    constructor(workspacePath: string, options?: LocalStoreOptions);
+    get workspaceFile(): string;
+    get lockFile(): string;
+    /** `<root>/areas/<slug>`. */
+    areaDir(slug: string): string;
+    /** `<root>/areas/<slug>/area.yml`. */
+    areaFile(slug: string): string;
+    /**
+     * Directory holding entities of `kind`. Area-scoped kinds require `area`;
+     * issues live in the area dir when `area` is given and in `<root>/issues` otherwise.
+     */
+    entityDir(kind: EntityKind, area?: string | null): string;
+    /** Absolute path of an entity file. */
+    entityPath(kind: EntityKind, entityNumber: string, area?: string | null): string;
+    /** `<root>/documents/<slug>.md`. */
+    documentPath(slug: string): string;
+    /** True when `<root>/workspace.yml` exists. */
+    isWorkspace(): Promise<boolean>;
+    /**
+     * Create the full directory layout of §4.1 plus `workspace.yml`, and optionally the
+     * first area. Idempotent: re-scaffolding an existing workspace only fills in gaps and
+     * leaves `workspace.yml` (and its counters) untouched.
+     */
+    scaffold(options: ScaffoldOptions): Promise<WorkspaceFile>;
+    /**
+     * Create `areas/<slug>/` with its `tasks/`, `issues/`, `vibes/` subdirectories and
+     * `area.yml`. Returns the existing `area.yml` untouched when the area already exists.
+     */
+    scaffoldArea(input: CreateAreaInput): Promise<AreaFile>;
+    readWorkspace(): Promise<WorkspaceFile>;
+    writeWorkspace(workspace: WorkspaceFile): Promise<void>;
+    readArea(slug: string): Promise<AreaFile>;
+    tryReadArea(slug: string): Promise<AreaFile | undefined>;
+    writeArea(area: AreaFile): Promise<void>;
+    /** Every area in the workspace, ordered by slug. */
+    listAreas(): Promise<AreaFile[]>;
+    /** Look an area up by slug; `undefined` when it does not exist. */
+    findAreaBySlug(slug: string): Promise<AreaFile | undefined>;
+    /**
+     * Run `fn` while holding the workspace's advisory `.lock` file.
+     *
+     * Guards multi-file operations (counter bump + entity write) against concurrent CLI
+     * invocations. Reentrant within one async context, serialised within one process, and
+     * retried `lockRetries` × `lockRetryDelayMs` against other processes before failing.
+     * The lock is always released in a `finally`.
+     */
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+    private acquireLockFile;
+    private releaseLockFile;
+    /**
+     * Bump the counter for `kind` in `workspace.yml` and return the new entity number.
+     * Runs under the advisory lock, so concurrent creates never collide.
+     */
+    nextEntityNumber(kind: EntityKind): Promise<string>;
+    /**
+     * Allocate the next entity number and write the file in a single locked operation.
+     * `build` receives the freshly allocated number and returns the record to persist.
+     */
+    createEntity<K extends EntityKind>(kind: K, build: (entityNumber: string) => {
+        frontmatter: RecordFor<K>;
+        body?: string;
+    }, options?: {
+        area?: string | null;
+    }): Promise<FoundEntity<K>>;
+    /** Read an entity file by kind + number. Throws `NOT_FOUND` when missing. */
+    readEntity<K extends EntityKind>(kind: K, entityNumber: string, options?: {
+        area?: string | null;
+    }): Promise<FoundEntity<K>>;
+    /** Read an entity file by kind + number, or `undefined` when it does not exist. */
+    tryReadEntity<K extends EntityKind>(kind: K, entityNumber: string, options?: {
+        area?: string | null;
+    }): Promise<FoundEntity<K> | undefined>;
+    /** Persist an entity file that was previously read (or built) by the store. */
+    writeEntity<K extends EntityKind>(file: FoundEntity<K>): Promise<void>;
+    /** Write a raw frontmatter+body pair to an explicit path (atomic). */
+    writeFileRecord(path: string, frontmatter: LocalRecord, body?: string): Promise<void>;
+    /**
+     * Locate any entity by its entity number (`TS-000001`) or by its uuid.
+     *
+     * Entity numbers resolve directly from the prefix + directory layout; uuids require a
+     * scan of the workspace (small by construction). Returns `undefined` when not found.
+     */
+    findEntity(ref: string): Promise<FoundEntity | undefined>;
+    /** Like {@link findEntity} but throws `NOT_FOUND` instead of returning `undefined`. */
+    requireEntity(ref: string): Promise<FoundEntity>;
+    /**
+     * All entities of one kind.
+     *
+     * - Area-scoped kinds (`task`, `vibe`): `area` restricts to that area; omitting it
+     *   walks every area.
+     * - `issue`: `area` restricts to that area; omitting it returns workspace-level issues
+     *   *and* every area's issues.
+     * - Workspace-scoped kinds: `area` is ignored.
+     *
+     * Results are sorted by entity number for stable output.
+     */
+    listEntities<K extends EntityKind>(kind: K, options?: {
+        area?: string | null;
+    }): Promise<FoundEntity<K>[]>;
+    /** Read `documents/<slug>.md`, or `undefined` when it does not exist. */
+    findDocumentBySlug(slug: string): Promise<LocalFile<DocumentRecord> | undefined>;
+    /** Like {@link findDocumentBySlug} but throws `NOT_FOUND` when missing. */
+    readDocument(slug: string): Promise<LocalFile<DocumentRecord>>;
+    /** Every document in `documents/`, ordered by slug. */
+    listDocuments(): Promise<LocalFile<DocumentRecord>[]>;
+    /** Write `documents/<slug>.md` atomically. */
+    writeDocument(frontmatter: DocumentRecord, body: string): Promise<LocalFile<DocumentRecord>>;
+    /** Area slugs (or `null` for workspace scope) to search for `kind`. */
+    private scopesFor;
+    /** Every path an entity number could occupy, in search order. */
+    private candidatePaths;
+    private readEntityAt;
+}
+/**
+ * Atomic write: serialise to `<file>.tmp` in the same directory, then rename over the
+ * target. The temp file is removed on any failure, so no `.tmp` litter is left behind.
+ */
+export declare function writeAtomic(path: string, content: string): Promise<void>;
+/** Fresh counters, all at zero. */
+export declare function emptyCounters(): WorkspaceCounters;
+/** ISO-8601 UTC, second precision — the timestamp format used across the format. */
+export declare function nowIso(): string;
+/** Lowercase, dash-separated slug — used for workspace/area defaults. */
+export declare function slugify(value: string): string;