@graypirate/tabula 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# Tabula Core
+
+Core API and command-line interface for Tabula.
+
+## Global Installation
+
+After the package is published, install the Core package and CLI from the npm registry:
+
+```bash
+bun add --global @graypirate/tabula
+```
+
+Verify:
+```bash
+command -v tabula
+tabula list
+```
+
+Upgrade or remove the Core package with Bun:
+```bash
+bun update --global @graypirate/tabula
+bun remove --global @graypirate/tabula
+```
+
+## CLI
+
+Most commands follow one of these forms:
+```bash
+tabula <command> [arguments] [options]
+tabula <command> <subcommand> [arguments] [options]
+```
+
+Current command groups:
+- `init [options]`
+- `list [id] [options]`
+- `read [id] [options]`
+- `create object [options]`
+- `create block [options]`
+- `write [options]`
+- `search <query> [options]`
+- `delete [id] [options]`
+
+Common argument patterns:
+- `[id]` is an optional entity identifier for commands that can target either a root context or a specific entity.
+- `<query>` is a required search string.
+- `[options]` includes flags such as `--workspace`, `--parent`, `--name`, `--content`, `--type`, and repeatable `--property key=value`.
+
+Entity IDs identify their type:
+- `d_...`: workspace
+- `o_...`: Object
+- `b_...`: Block
+
+Commands that operate inside a workspace require `--workspace NAME`.
+
+### Workspaces
+
+```bash
+tabula init --workspace example
+tabula list
+tabula read --workspace example
+tabula list --workspace example
+tabula delete --workspace example
+```
+
+`init` creates or opens `~/.tabula/<name>.sqlite` and returns workspace
+metadata. Bare `list` returns managed workspace names. `read --workspace`
+returns metadata, while `list --workspace` returns ordered root Object IDs.
+
+Workspace deletion removes the SQLite file and its sidecars. Interactive
+terminals ask for confirmation; non-interactive commands do not prompt.
+
+### Create Objects and Blocks
+
+```bash
+tabula create object \
+  --workspace example \
+  --name "Project" \
+  --property status=active
+
+tabula create block \
+  --workspace example \
+  --parent o_parent \
+  --content "First task" \
+  --property complete=false
+```
+
+Objects may be created at the workspace root or under an Object or Block.
+Blocks require `--parent`. Repeat `--property key=value` to add properties;
+values are parsed as JSON when valid and otherwise remain strings.
+
+### Write Recursive Trees
+
+`write` accepts exactly one recursive Object or Block JSON value from stdin:
+
+```bash
+tabula write --workspace example <<'JSON'
+{
+  "type": "object",
+  "name": "Document",
+  "properties": { "status": "draft" },
+  "children": [
+    {
+      "type": "block",
+      "content": "Introduction",
+      "properties": { "level": 1 },
+      "children": []
+    }
+  ]
+}
+JSON
+```
+
+New entities omit `id`. Supplying an existing ID replaces that entity.
+Submitted `children` arrays are complete replacements: omitted child subtrees
+are deleted. Existing children included by ID may be moved. Object roots may be
+written at workspace root; Block roots require `--parent ID`.
+
+### Read, List, Search, and Delete
+
+```bash
+tabula read o_example --workspace example
+tabula list o_example --workspace example
+tabula search "draft" --workspace example
+tabula search "draft" --workspace example --type block
+tabula delete b_example --workspace example
+```
+
+`read ID` returns the parent ID and complete recursive entity tree. `list ID`
+returns ordered direct child IDs. `search` checks Object names and properties
+plus Block content and properties. Entity deletion removes the entity and all
+descendants.
+
+### Output and Errors
+
+Successful commands write one compact JSON value plus a newline to stdout and
+exit `0`. Input and validation failures write structured JSON to stderr and
+exit `2`; operation failures exit `1`.
+
+```json
+{"error":{"code":"MISSING_OPTION","message":"Required option missing: --workspace"}}
+```

package/dist/API/create.d.ts

@@ -0,0 +1,33 @@
+import type { Database } from "bun:sqlite";
+import type { JSONRecord } from "../src/types/json";
+import { type BlockResult, type Create, type Result, type ObjectResult } from "./types";
+type CreateOptions = {
+    parentID?: string;
+};
+/**
+ * Creates an object or block with no children.
+ * @param db - The SQLite database backing the workspace
+ * @param input - The object or block creation input
+ * @param options - Optional parent placement
+ * @returns The parent-aware created entity result
+ */
+export declare function create(db: Database, input: Create, options?: CreateOptions): Result;
+/**
+ * Creates an object with no children.
+ * @param db - The SQLite database backing the workspace
+ * @param name - The object name
+ * @param properties - Optional object properties
+ * @param options - Optional parent placement
+ * @returns The created recursive object
+ */
+export declare function createObject(db: Database, name: string, properties?: JSONRecord, options?: CreateOptions): ObjectResult;
+/**
+ * Creates a block with no children.
+ * @param db - The SQLite database backing the workspace
+ * @param content - The block text content
+ * @param properties - Optional block properties
+ * @param options - Optional parent placement
+ * @returns The created recursive block
+ */
+export declare function createBlock(db: Database, content: string, properties?: JSONRecord, options?: CreateOptions): BlockResult;
+export {};

package/dist/API/create.js

@@ -0,0 +1,91 @@
+import { blockExists, createEntity as createStoredEntity, objectExists, readEntityParentID, readEntityTree, } from "../src/storage";
+import { createBlockID, createObjID } from "../src/utils/id";
+import {} from "./types";
+/**
+ * Creates an object or block with no children.
+ * @param db - The SQLite database backing the workspace
+ * @param input - The object or block creation input
+ * @param options - Optional parent placement
+ * @returns The parent-aware created entity result
+ */
+export function create(db, input, options = {}) {
+    const entity = buildEntity(db, input);
+    createStoredEntity(db, entity, options.parentID ?? undefined);
+    return entityResult(db, entity.id);
+}
+/**
+ * Creates an object with no children.
+ * @param db - The SQLite database backing the workspace
+ * @param name - The object name
+ * @param properties - Optional object properties
+ * @param options - Optional parent placement
+ * @returns The created recursive object
+ */
+export function createObject(db, name, properties = {}, options = {}) {
+    const result = create(db, {
+        type: "object",
+        name,
+        properties,
+    }, options);
+    assertObjectResult(result);
+    return result;
+}
+/**
+ * Creates a block with no children.
+ * @param db - The SQLite database backing the workspace
+ * @param content - The block text content
+ * @param properties - Optional block properties
+ * @param options - Optional parent placement
+ * @returns The created recursive block
+ */
+export function createBlock(db, content, properties = {}, options = {}) {
+    const result = create(db, {
+        type: "block",
+        content,
+        properties,
+    }, options);
+    assertBlockResult(result);
+    return result;
+}
+function buildEntity(db, input) {
+    if (input.type === "object") {
+        return {
+            id: createAvailableID(createObjID, (id) => objectExists(db, id)),
+            type: "object",
+            name: input.name,
+            properties: input.properties ?? {},
+            children: [],
+        };
+    }
+    return {
+        id: createAvailableID(createBlockID, (id) => blockExists(db, id)),
+        type: "block",
+        content: input.content,
+        properties: input.properties ?? {},
+        children: [],
+    };
+}
+function entityResult(db, entityID) {
+    return {
+        parentID: readEntityParentID(db, entityID),
+        entity: readEntityTree(db, entityID),
+    };
+}
+function assertObjectResult(result) {
+    if (result.entity.type !== "object") {
+        throw new Error("Expected object result");
+    }
+}
+function assertBlockResult(result) {
+    if (result.entity.type !== "block") {
+        throw new Error("Expected block result");
+    }
+}
+/** Generates an entity ID that is not already stored. */
+function createAvailableID(createID, exists) {
+    let id = createID();
+    while (exists(id)) {
+        id = createID();
+    }
+    return id;
+}

package/dist/API/delete.d.ts

@@ -0,0 +1,31 @@
+import type { Database } from "bun:sqlite";
+import type { BlockID } from "../src/types/block";
+import type { ObjID } from "../src/types/object";
+/**
+ * Deletes the managed SQLite files for a workspace name.
+ * @param workspace - Managed workspace name
+ * @returns True when the workspace was deleted
+ * @throws If the workspace does not exist
+ */
+export declare function deleteWorkspace(workspace: string): boolean;
+/**
+ * Deletes an object or block and its recursive containment subtree.
+ * @param db - The SQLite database backing the workspace
+ * @param entityID - The object or block ID to delete
+ * @returns True if the entity existed and was deleted
+ */
+export declare function deleteEntity(db: Database, entityID: string): boolean;
+/**
+ * Deletes an object and its recursive containment subtree.
+ * @param db - The SQLite database backing the workspace
+ * @param objectID - The object ID to delete
+ * @returns True if the object existed and was deleted
+ */
+export declare function deleteObject(db: Database, objectID: ObjID): boolean;
+/**
+ * Deletes a block and its recursive containment subtree.
+ * @param db - The SQLite database backing the workspace
+ * @param blockID - The block ID to delete
+ * @returns True if the block existed and was deleted
+ */
+export declare function deleteBlock(db: Database, blockID: BlockID): boolean;

package/dist/API/delete.js

@@ -0,0 +1,38 @@
+import { deleteEntityTree } from "../src/storage";
+import { deleteWorkspaceFiles } from "../src/workspace";
+/**
+ * Deletes the managed SQLite files for a workspace name.
+ * @param workspace - Managed workspace name
+ * @returns True when the workspace was deleted
+ * @throws If the workspace does not exist
+ */
+export function deleteWorkspace(workspace) {
+    return deleteWorkspaceFiles(workspace);
+}
+/**
+ * Deletes an object or block and its recursive containment subtree.
+ * @param db - The SQLite database backing the workspace
+ * @param entityID - The object or block ID to delete
+ * @returns True if the entity existed and was deleted
+ */
+export function deleteEntity(db, entityID) {
+    return deleteEntityTree(db, entityID);
+}
+/**
+ * Deletes an object and its recursive containment subtree.
+ * @param db - The SQLite database backing the workspace
+ * @param objectID - The object ID to delete
+ * @returns True if the object existed and was deleted
+ */
+export function deleteObject(db, objectID) {
+    return deleteEntity(db, objectID);
+}
+/**
+ * Deletes a block and its recursive containment subtree.
+ * @param db - The SQLite database backing the workspace
+ * @param blockID - The block ID to delete
+ * @returns True if the block existed and was deleted
+ */
+export function deleteBlock(db, blockID) {
+    return deleteEntity(db, blockID);
+}

package/dist/API/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./create";
+export * from "./delete";
+export * from "./init";
+export * from "./read";
+export * from "./search";
+export * from "./types";
+export * from "./validation";
+export * from "./write";
+export { InvalidWorkspaceNameError, listWorkspaceNames, validateWorkspaceName, } from "../src/workspace";
+export type { Block, BlockID, BlockMetadata, } from "../src/types/block";
+export type { Entity, EntityID, EntityParentID, EntityReference, EntityType, } from "../src/types/graph";
+export type { Obj, ObjID, ObjMetadata, } from "../src/types/object";
+export type { WorkspaceID, WorkspaceMetadata, } from "../src/types/workspace";

package/dist/API/index.js

@@ -0,0 +1,9 @@
+export * from "./create";
+export * from "./delete";
+export * from "./init";
+export * from "./read";
+export * from "./search";
+export * from "./types";
+export * from "./validation";
+export * from "./write";
+export { InvalidWorkspaceNameError, listWorkspaceNames, validateWorkspaceName, } from "../src/workspace";

package/dist/API/init.d.ts

@@ -0,0 +1,3 @@
+import type { Database } from "bun:sqlite";
+export declare function initializeWorkspace(name: string): Database;
+export declare function openWorkspace(name: string): Database;

package/dist/API/init.js

@@ -0,0 +1,8 @@
+import { resolveInitializedWorkspaceDatabasePath, resolveWorkspaceDatabasePath, } from "../src/workspace";
+import { initializeStorage, openStorage, } from "../src/storage";
+export function initializeWorkspace(name) {
+    return initializeStorage(resolveInitializedWorkspaceDatabasePath(name), name);
+}
+export function openWorkspace(name) {
+    return openStorage(resolveWorkspaceDatabasePath(name));
+}

package/dist/API/read.d.ts

@@ -0,0 +1,60 @@
+import type { Database } from "bun:sqlite";
+import type { BlockID } from "../src/types/block";
+import type { EntityID } from "../src/types/graph";
+import type { ObjID } from "../src/types/object";
+import type { WorkspaceMetadata } from "../src/types/workspace";
+import { type BlockResult, type Result, type ObjectResult } from "./types";
+/**
+ * Reads an object or block as a parent-aware recursive entity result.
+ * @param db - The SQLite database backing the workspace
+ * @param id - The object or block ID to read
+ * @returns The parent-aware recursive entity result
+ */
+export declare function readEntity(db: Database, id: string): Result;
+/**
+ * Reads workspace metadata.
+ * @param db - The SQLite database backing the workspace
+ * @returns The workspace metadata
+ */
+export declare function readWorkspace(db: Database): WorkspaceMetadata;
+/**
+ * Reads an object as a recursive entity tree.
+ * @param db - The SQLite database backing the workspace
+ * @param objectID - The object ID to read
+ * @returns The recursive object
+ */
+export declare function readObject(db: Database, objectID: ObjID): ObjectResult;
+/**
+ * Reads a block as a recursive entity tree.
+ * @param db - The SQLite database backing the workspace
+ * @param blockID - The block ID to read
+ * @returns The recursive block
+ */
+export declare function readBlock(db: Database, blockID: BlockID): BlockResult;
+/**
+ * Lists the workspace shape as ordered root object IDs.
+ * @param db - The SQLite database backing the workspace
+ * @returns The ordered root object IDs
+ */
+export declare function listWorkspace(db: Database): ObjID[];
+/**
+ * Lists the direct child IDs for an object or block.
+ * @param db - The SQLite database backing the workspace
+ * @param entityID - The object or block ID to list
+ * @returns The ordered direct child IDs
+ */
+export declare function listEntity(db: Database, entityID: EntityID): EntityID[];
+/**
+ * Lists direct child IDs for an object.
+ * @param db - The SQLite database backing the workspace
+ * @param objectID - The object ID to list
+ * @returns The ordered direct child IDs
+ */
+export declare function listObject(db: Database, objectID: ObjID): EntityID[];
+/**
+ * Lists direct child IDs for a block.
+ * @param db - The SQLite database backing the workspace
+ * @param blockID - The block ID to list
+ * @returns The ordered direct child IDs
+ */
+export declare function listBlock(db: Database, blockID: BlockID): EntityID[];

package/dist/API/read.js

@@ -0,0 +1,95 @@
+import { readDatabaseRootObjects, readDirectEntityChildIDs, readDatabaseMetadata, readEntityParentID, readEntityTree, } from "../src/storage";
+import {} from "./types";
+// Read functions
+/**
+ * Reads an object or block as a parent-aware recursive entity result.
+ * @param db - The SQLite database backing the workspace
+ * @param id - The object or block ID to read
+ * @returns The parent-aware recursive entity result
+ */
+export function readEntity(db, id) {
+    return entityResult(db, readEntityTree(db, id));
+}
+/**
+ * Reads workspace metadata.
+ * @param db - The SQLite database backing the workspace
+ * @returns The workspace metadata
+ */
+export function readWorkspace(db) {
+    return readDatabaseMetadata(db);
+}
+/**
+ * Reads an object as a recursive entity tree.
+ * @param db - The SQLite database backing the workspace
+ * @param objectID - The object ID to read
+ * @returns The recursive object
+ */
+export function readObject(db, objectID) {
+    const result = readEntity(db, objectID);
+    assertObjectResult(result);
+    return result;
+}
+/**
+ * Reads a block as a recursive entity tree.
+ * @param db - The SQLite database backing the workspace
+ * @param blockID - The block ID to read
+ * @returns The recursive block
+ */
+export function readBlock(db, blockID) {
+    const result = readEntity(db, blockID);
+    assertBlockResult(result);
+    return result;
+}
+// List functions
+/**
+ * Lists the workspace shape as ordered root object IDs.
+ * @param db - The SQLite database backing the workspace
+ * @returns The ordered root object IDs
+ */
+export function listWorkspace(db) {
+    return readDatabaseRootObjects(db);
+}
+/**
+ * Lists the direct child IDs for an object or block.
+ * @param db - The SQLite database backing the workspace
+ * @param entityID - The object or block ID to list
+ * @returns The ordered direct child IDs
+ */
+export function listEntity(db, entityID) {
+    return readDirectEntityChildIDs(db, entityID);
+}
+/**
+ * Lists direct child IDs for an object.
+ * @param db - The SQLite database backing the workspace
+ * @param objectID - The object ID to list
+ * @returns The ordered direct child IDs
+ */
+export function listObject(db, objectID) {
+    return listEntity(db, objectID);
+}
+/**
+ * Lists direct child IDs for a block.
+ * @param db - The SQLite database backing the workspace
+ * @param blockID - The block ID to list
+ * @returns The ordered direct child IDs
+ */
+export function listBlock(db, blockID) {
+    return listEntity(db, blockID);
+}
+// Internal helpers
+function entityResult(db, entity) {
+    return {
+        parentID: readEntityParentID(db, entity.id),
+        entity,
+    };
+}
+function assertObjectResult(result) {
+    if (result.entity.type !== "object") {
+        throw new Error("Expected object result");
+    }
+}
+function assertBlockResult(result) {
+    if (result.entity.type !== "block") {
+        throw new Error("Expected block result");
+    }
+}

package/dist/API/search.d.ts

@@ -0,0 +1,4 @@
+import type { Database } from "bun:sqlite";
+import { type SearchResult, type SearchType } from "../src/storage";
+export type { SearchResult, SearchType } from "../src/storage";
+export declare function search(db: Database, query: string, type?: SearchType): SearchResult[];

package/dist/API/search.js

@@ -0,0 +1,4 @@
+import { searchEntities } from "../src/storage";
+export function search(db, query, type) {
+    return searchEntities(db, query, type);
+}

package/dist/API/types.d.ts

@@ -0,0 +1,23 @@
+import type { Block, BlockID } from "../src/types/block";
+import type { Entity, EntityParentID } from "../src/types/graph";
+import type { Obj, ObjID } from "../src/types/object";
+export type { EntityParentID } from "../src/types/graph";
+export type { JSONPrimitive, JSONRecord, JSONValue } from "../src/types/json";
+export type Create = ObjectCreate | BlockCreate;
+export type ObjectCreate = Omit<Obj, "id" | "children">;
+export type BlockCreate = Omit<Block, "id" | "children">;
+export interface Result<T extends Entity = Entity> {
+    parentID: EntityParentID | null;
+    entity: T;
+}
+export type ObjectResult = Result<Obj>;
+export type BlockResult = Result<Block>;
+export type Write = ObjectWrite | BlockWrite;
+export type BlockWrite = Omit<Block, "id" | "children"> & {
+    id?: BlockID;
+    children: Write[];
+};
+export type ObjectWrite = Omit<Obj, "id" | "children"> & {
+    id?: ObjID;
+    children: Write[];
+};

package/dist/API/validation.d.ts

@@ -0,0 +1,8 @@
+import type { Write } from "./types";
+export declare class TabulaInputError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    readonly name = "TabulaInputError";
+    constructor(code: string, message: string, details?: unknown | undefined);
+}
+export declare function validateWriteInput(value: unknown): Write;

package/dist/API/validation.js

@@ -0,0 +1,103 @@
+const blockFields = new Set(["id", "type", "content", "properties", "children"]);
+const objectFields = new Set(["id", "type", "name", "properties", "children"]);
+export class TabulaInputError extends Error {
+    code;
+    details;
+    name = "TabulaInputError";
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+export function validateWriteInput(value) {
+    const explicitIDs = new Set();
+    return validateEntityWrite(value, "$", explicitIDs);
+}
+function validateEntityWrite(value, path, explicitIDs) {
+    const object = requireObject(value, path);
+    const type = requiredString(object, "type", `${path}.type`);
+    if (type === "object") {
+        return validateObjectWrite(object, path, explicitIDs);
+    }
+    if (type === "block") {
+        return validateBlockWrite(object, path, explicitIDs);
+    }
+    throw inputError("INVALID_ENTITY_TYPE", `Invalid entity type at ${path}.type: ${type}`, {
+        path: `${path}.type`,
+    });
+}
+function validateObjectWrite(value, path, explicitIDs) {
+    rejectUnknownFields(value, objectFields, path);
+    const id = optionalID(value, "id", "o_", `${path}.id`, explicitIDs);
+    const children = requiredArray(value, "children", `${path}.children`);
+    return {
+        ...(id === undefined ? {} : { id }),
+        type: "object",
+        name: requiredString(value, "name", `${path}.name`),
+        ...optionalProperties(value, `${path}.properties`),
+        children: children.map((child, index) => validateEntityWrite(child, `${path}.children[${index}]`, explicitIDs)),
+    };
+}
+function validateBlockWrite(value, path, explicitIDs) {
+    rejectUnknownFields(value, blockFields, path);
+    const id = optionalID(value, "id", "b_", `${path}.id`, explicitIDs);
+    const children = requiredArray(value, "children", `${path}.children`);
+    return {
+        ...(id === undefined ? {} : { id }),
+        type: "block",
+        content: requiredString(value, "content", `${path}.content`),
+        ...optionalProperties(value, `${path}.properties`),
+        children: children.map((child, index) => validateEntityWrite(child, `${path}.children[${index}]`, explicitIDs)),
+    };
+}
+function requireObject(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw inputError("INVALID_OBJECT", `Expected object at ${path}`, { path });
+    }
+    return value;
+}
+function rejectUnknownFields(value, allowed, path) {
+    for (const field of Object.keys(value)) {
+        if (!allowed.has(field)) {
+            throw inputError("UNKNOWN_FIELD", `Unknown field at ${path}: ${field}`, { path, field });
+        }
+    }
+}
+function requiredString(value, field, path) {
+    const result = value[field];
+    if (typeof result !== "string") {
+        throw inputError("INVALID_FIELD", `Expected string at ${path}`, { path });
+    }
+    return result;
+}
+function requiredArray(value, field, path) {
+    const result = value[field];
+    if (!Array.isArray(result)) {
+        throw inputError("INVALID_FIELD", `Expected array at ${path}`, { path });
+    }
+    return result;
+}
+function optionalID(value, field, prefix, path, explicitIDs) {
+    if (!Object.hasOwn(value, field)) {
+        return undefined;
+    }
+    const id = requiredString(value, field, path);
+    if (!id.startsWith(prefix)) {
+        throw inputError("INVALID_ID", `Expected ${prefix} ID at ${path}: ${id}`, { path });
+    }
+    if (explicitIDs.has(id)) {
+        throw inputError("DUPLICATE_ENTITY_ID", `Duplicate entity ID: ${id}`, { path });
+    }
+    explicitIDs.add(id);
+    return id;
+}
+function optionalProperties(value, path) {
+    if (!Object.hasOwn(value, "properties")) {
+        return {};
+    }
+    return { properties: requireObject(value.properties, path) };
+}
+function inputError(code, message, details) {
+    return new TabulaInputError(code, message, details);
+}