@graypirate/tabula 1.0.0

package/dist/API/write.d.ts

@@ -0,0 +1,30 @@
+import type { Database } from "bun:sqlite";
+import { type BlockResult, type Result, type ObjectResult, type BlockWrite, type ObjectWrite, type Write } from "./types";
+type WriteOptions = {
+    parentID?: string;
+};
+/**
+ * Creates or replaces an object or block tree.
+ * @param db - The SQLite database backing the workspace
+ * @param input - The recursive entity input
+ * @param options - Optional parent placement for the root entity
+ * @returns The stored parent-aware recursive entity result
+ */
+export declare function writeEntity(db: Database, input: Write, options?: WriteOptions): Result;
+/**
+ * Creates or replaces a block tree.
+ * @param db - The SQLite database backing the workspace
+ * @param input - The recursive block input
+ * @param options - Optional parent placement for the root block
+ * @returns The stored recursive block tree
+ */
+export declare function writeBlock(db: Database, input: BlockWrite, options?: WriteOptions): BlockResult;
+/**
+ * Creates or replaces an object tree.
+ * @param db - The SQLite database backing the workspace
+ * @param input - The recursive object input
+ * @param options - Optional parent placement for the root object
+ * @returns The stored recursive object tree
+ */
+export declare function writeObject(db: Database, input: ObjectWrite, options?: WriteOptions): ObjectResult;
+export {};

package/dist/API/write.js

@@ -0,0 +1,90 @@
+import { entityExists, readEntityParentID, writeEntityTree, } from "../src/storage";
+import { createBlockID, createObjID } from "../src/utils/id";
+import {} from "./types";
+/**
+ * Creates or replaces an object or block tree.
+ * @param db - The SQLite database backing the workspace
+ * @param input - The recursive entity input
+ * @param options - Optional parent placement for the root entity
+ * @returns The stored parent-aware recursive entity result
+ */
+export function writeEntity(db, input, options = {}) {
+    const entity = prepareEntity(db, input);
+    const stored = writeEntityTree(db, entity, options.parentID ?? undefined);
+    return {
+        parentID: readEntityParentID(db, stored.id),
+        entity: stored,
+    };
+}
+/**
+ * Creates or replaces a block tree.
+ * @param db - The SQLite database backing the workspace
+ * @param input - The recursive block input
+ * @param options - Optional parent placement for the root block
+ * @returns The stored recursive block tree
+ */
+export function writeBlock(db, input, options = {}) {
+    const result = writeEntity(db, input, options);
+    assertBlockResult(result);
+    return result;
+}
+/**
+ * Creates or replaces an object tree.
+ * @param db - The SQLite database backing the workspace
+ * @param input - The recursive object input
+ * @param options - Optional parent placement for the root object
+ * @returns The stored recursive object tree
+ */
+export function writeObject(db, input, options = {}) {
+    const result = writeEntity(db, input, options);
+    assertObjectResult(result);
+    return result;
+}
+/** Assigns IDs while producing a recursive public entity tree. */
+function prepareEntity(db, input) {
+    const usedIDs = new Set();
+    const visit = (entity) => {
+        const id = entity.id ?? createAvailableEntityID(db, entity.type, usedIDs);
+        if (usedIDs.has(id)) {
+            throw new Error(`Duplicate entity ID in write tree: ${id}`);
+        }
+        usedIDs.add(id);
+        const children = entity.children.map(visit);
+        if (entity.type === "object") {
+            return {
+                id,
+                type: "object",
+                name: entity.name,
+                properties: entity.properties ?? {},
+                children,
+            };
+        }
+        return {
+            id,
+            type: "block",
+            content: entity.content,
+            properties: entity.properties ?? {},
+            children,
+        };
+    };
+    return visit(input);
+}
+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 unused entity ID for the requested entity type. */
+function createAvailableEntityID(db, type, reserved) {
+    const createID = type === "object" ? createObjID : createBlockID;
+    let id = createID();
+    while (reserved.has(id) || entityExists(db, id)) {
+        id = createID();
+    }
+    return id;
+}

package/dist/CLI/arguments.d.ts

@@ -0,0 +1,45 @@
+export type EntityType = "workspace" | "object" | "block";
+export type SearchType = Exclude<EntityType, "workspace">;
+export type CLICommand = {
+    action: "init";
+    workspace: string;
+} | {
+    action: "create";
+    entity: "object";
+    workspace: string;
+    name: string;
+    propertyValues: string[];
+    parentID?: string;
+} | {
+    action: "create";
+    entity: "block";
+    workspace: string;
+    content: string;
+    propertyValues: string[];
+    parentID: string;
+} | {
+    action: "write";
+    workspace: string;
+    parentID?: string;
+} | {
+    action: "read";
+    workspace: string;
+    id?: string;
+} | {
+    action: "listWorkspaces";
+} | {
+    action: "list";
+    workspace: string;
+    id?: string;
+} | {
+    action: "delete";
+    workspace: string;
+    id?: string;
+} | {
+    action: "search";
+    workspace: string;
+    query: string;
+    type?: SearchType;
+};
+export declare function parseCommand(argv: string[]): CLICommand;
+export declare function inferEntityType(id: string): EntityType;

package/dist/CLI/arguments.js

@@ -0,0 +1,263 @@
+import { InvalidWorkspaceNameError, validateWorkspaceName, } from "../index.js";
+import { CLIInputError } from "./errors.js";
+const optionNames = new Set([
+    "content",
+    "name",
+    "parent",
+    "property",
+    "type",
+    "workspace",
+]);
+export function parseCommand(argv) {
+    const parsed = parseArguments(argv);
+    const action = parsed.positionals[0];
+    if (action === undefined) {
+        throw inputError("INVALID_COMMAND", "Command is required");
+    }
+    switch (action) {
+        case "list": {
+            if (parsed.positionals.length === 1 && !parsed.options.has("workspace")) {
+                allowOptions(parsed, []);
+                return { action: "listWorkspaces" };
+            }
+            const workspace = requireCommandWorkspace(parsed);
+            if (parsed.positionals.length > 2) {
+                throw inputError("INVALID_ARGUMENTS", "Usage: tabula list [ID] --workspace NAME");
+            }
+            allowOptions(parsed, ["workspace"]);
+            const id = parsed.positionals[1];
+            if (id !== undefined) {
+                inferEntityType(id);
+            }
+            return id === undefined
+                ? { action, workspace }
+                : { action, workspace, id };
+        }
+        case "init": {
+            const workspace = requireCommandWorkspace(parsed);
+            requirePositionals(parsed, 1, "tabula init --workspace NAME");
+            allowOptions(parsed, ["workspace"]);
+            return {
+                action,
+                workspace,
+            };
+        }
+        case "create": {
+            const workspace = requireCommandWorkspace(parsed);
+            return parseCreate(parsed, workspace);
+        }
+        case "write": {
+            const workspace = requireCommandWorkspace(parsed);
+            requirePositionals(parsed, 1, "tabula write --workspace NAME [--parent ID] < entity.json");
+            allowOptions(parsed, ["workspace", "parent"]);
+            const parentID = optionalParentID(parsed);
+            return parentID === undefined
+                ? { action, workspace }
+                : { action, workspace, parentID };
+        }
+        case "read": {
+            const workspace = requireCommandWorkspace(parsed);
+            if (parsed.positionals.length > 2) {
+                throw inputError("INVALID_ARGUMENTS", "Usage: tabula read [ID] --workspace NAME");
+            }
+            allowOptions(parsed, ["workspace"]);
+            const id = parsed.positionals[1];
+            if (id !== undefined) {
+                inferEntityType(id);
+            }
+            return id === undefined
+                ? { action, workspace }
+                : { action, workspace, id };
+        }
+        case "delete": {
+            const workspace = requireCommandWorkspace(parsed);
+            if (parsed.positionals.length > 2) {
+                throw inputError("INVALID_ARGUMENTS", "Usage: tabula delete [ID] --workspace NAME");
+            }
+            allowOptions(parsed, ["workspace"]);
+            const id = parsed.positionals[1];
+            if (id === undefined) {
+                return { action, workspace };
+            }
+            if (inferEntityType(id) === "workspace") {
+                throw inputError("UNSUPPORTED_DELETE", "Delete workspaces by name: tabula delete --workspace NAME");
+            }
+            return { action, workspace, id };
+        }
+        case "search": {
+            const workspace = requireCommandWorkspace(parsed);
+            requirePositionals(parsed, 2, "tabula search QUERY --workspace NAME [--type object|block]");
+            allowOptions(parsed, ["workspace", "type"]);
+            const type = optionalSingleOption(parsed, "type");
+            if (type !== undefined && !isSearchType(type)) {
+                throw inputError("INVALID_SEARCH_TYPE", `Invalid search type: ${type}`, { allowed: ["object", "block"] });
+            }
+            return {
+                action,
+                workspace,
+                query: parsed.positionals[1],
+                ...(type === undefined ? {} : { type }),
+            };
+        }
+        default:
+            throw inputError("INVALID_COMMAND", `Unknown command: ${action}`);
+    }
+}
+export function inferEntityType(id) {
+    switch (id.slice(0, 2)) {
+        case "d_":
+            return "workspace";
+        case "o_":
+            return "object";
+        case "b_":
+            return "block";
+        default:
+            throw inputError("INVALID_ID", `Unknown entity ID prefix: ${id}`);
+    }
+}
+function parseCreate(parsed, workspace) {
+    requirePositionals(parsed, 2, "tabula create object|block --workspace NAME [options]");
+    const entity = parsed.positionals[1];
+    switch (entity) {
+        case "object": {
+            allowOptions(parsed, ["workspace", "name", "parent", "property"]);
+            const parentID = optionalCreateParentID(parsed, entity);
+            return {
+                action: "create",
+                entity,
+                workspace,
+                name: requireSingleOption(parsed, "name"),
+                propertyValues: parsed.options.get("property") ?? [],
+                ...(parentID === undefined ? {} : { parentID }),
+            };
+        }
+        case "block": {
+            allowOptions(parsed, ["workspace", "content", "parent", "property"]);
+            const parentID = requireCreateParentID(parsed, entity);
+            return {
+                action: "create",
+                entity,
+                workspace,
+                content: requireSingleOption(parsed, "content"),
+                propertyValues: parsed.options.get("property") ?? [],
+                parentID,
+            };
+        }
+        default:
+            throw inputError("INVALID_ENTITY_TYPE", `Unknown create entity type: ${entity ?? ""}`, { allowed: ["object", "block"] });
+    }
+}
+function parseArguments(argv) {
+    const options = new Map();
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (!argument.startsWith("-")) {
+            positionals.push(argument);
+            continue;
+        }
+        if (!argument.startsWith("--")) {
+            throw inputError("UNKNOWN_OPTION", `Only long options are supported: ${argument}`);
+        }
+        const separator = argument.indexOf("=");
+        const name = argument.slice(2, separator === -1 ? undefined : separator);
+        if (!optionNames.has(name)) {
+            throw inputError("UNKNOWN_OPTION", `Unknown option: --${name}`);
+        }
+        const inlineValue = separator === -1 ? undefined : argument.slice(separator + 1);
+        const nextValue = argv[index + 1];
+        const value = inlineValue ?? nextValue;
+        if (value === undefined
+            || value.length === 0
+            || (inlineValue === undefined && value.startsWith("--"))) {
+            throw inputError("MISSING_OPTION_VALUE", `Option --${name} requires a value`);
+        }
+        if (inlineValue === undefined) {
+            index += 1;
+        }
+        const values = options.get(name) ?? [];
+        values.push(value);
+        options.set(name, values);
+    }
+    return { options, positionals };
+}
+function validateCommandWorkspaceName(workspace) {
+    try {
+        validateWorkspaceName(workspace);
+    }
+    catch (error) {
+        if (error instanceof InvalidWorkspaceNameError) {
+            throw inputError("INVALID_WORKSPACE_NAME", error.message, error.details);
+        }
+        throw error;
+    }
+}
+function requireCommandWorkspace(parsed) {
+    const workspace = requireSingleOption(parsed, "workspace");
+    validateCommandWorkspaceName(workspace);
+    return workspace;
+}
+function allowOptions(parsed, allowed) {
+    const allowedOptions = new Set(allowed);
+    for (const name of parsed.options.keys()) {
+        if (!allowedOptions.has(name)) {
+            throw inputError("INVALID_OPTION", `Option --${name} is not valid for this command`);
+        }
+    }
+}
+function requirePositionals(parsed, count, usage) {
+    if (parsed.positionals.length !== count) {
+        throw inputError("INVALID_ARGUMENTS", `Usage: ${usage}`);
+    }
+}
+function requireSingleOption(parsed, name) {
+    const value = optionalSingleOption(parsed, name);
+    if (value === undefined) {
+        throw inputError("MISSING_OPTION", `Required option missing: --${name}`);
+    }
+    return value;
+}
+function optionalSingleOption(parsed, name) {
+    const values = parsed.options.get(name);
+    if (values === undefined) {
+        return undefined;
+    }
+    if (values.length !== 1) {
+        throw inputError("DUPLICATE_OPTION", `Option --${name} may only be specified once`);
+    }
+    return values[0];
+}
+function optionalCreateParentID(parsed, childType) {
+    const parentID = optionalParentID(parsed);
+    if (parentID === undefined) {
+        return undefined;
+    }
+    validateParentType(parentID, childType);
+    return parentID;
+}
+function requireCreateParentID(parsed, childType) {
+    const parentID = optionalParentID(parsed);
+    if (parentID === undefined) {
+        throw inputError("MISSING_OPTION", "Required option missing: --parent");
+    }
+    validateParentType(parentID, childType);
+    return parentID;
+}
+function optionalParentID(parsed) {
+    const parentID = optionalSingleOption(parsed, "parent");
+    if (parentID !== undefined) {
+        inferEntityType(parentID);
+    }
+    return parentID;
+}
+function validateParentType(parentID, childType) {
+    if (childType === "block" && inferEntityType(parentID) === "workspace") {
+        throw inputError("INVALID_PARENT", `Workspace parents can only contain objects: ${parentID}`);
+    }
+}
+function isSearchType(value) {
+    return value === "object" || value === "block";
+}
+function inputError(code, message, details) {
+    return new CLIInputError(code, message, details);
+}

package/dist/CLI/dispatch.d.ts

@@ -0,0 +1,3 @@
+import { type CLICommand } from "./arguments.js";
+import type { WriteInput } from "./json.js";
+export declare function dispatchCommand(command: CLICommand, writeInput?: WriteInput): unknown;

package/dist/CLI/dispatch.js

@@ -0,0 +1,143 @@
+import { create, deleteEntity as deleteAPIEntity, deleteWorkspace, initializeWorkspace, listEntity as listAPIEntity, listWorkspaceNames, listWorkspace, openWorkspace, readEntity as readAPIEntity, readWorkspace, search, writeEntity, } from "../index.js";
+import { inferEntityType } from "./arguments.js";
+import { CLIInputError, CLIOperationError } from "./errors.js";
+import { parseProperties } from "./properties.js";
+export function dispatchCommand(command, writeInput) {
+    if (command.action === "init") {
+        return withInitializedWorkspace(command.workspace, readWorkspace);
+    }
+    if (command.action === "listWorkspaces") {
+        return listWorkspaceNames();
+    }
+    if (command.action === "delete" && command.id === undefined) {
+        try {
+            return deleteWorkspace(command.workspace);
+        }
+        catch (error) {
+            throw operationError("WORKSPACE_DELETE_FAILED", error, {
+                workspace: command.workspace,
+            });
+        }
+    }
+    const properties = command.action === "create"
+        ? parseProperties(command.propertyValues)
+        : {};
+    let db;
+    try {
+        db = openWorkspace(command.workspace);
+    }
+    catch (error) {
+        throw operationError("WORKSPACE_OPEN_FAILED", error, {
+            workspace: command.workspace,
+        });
+    }
+    try {
+        switch (command.action) {
+            case "create": {
+                switch (command.entity) {
+                    case "object":
+                        return create(db, {
+                            type: "object",
+                            name: command.name,
+                            properties,
+                        }, createOptions(command.parentID));
+                    case "block":
+                        return create(db, {
+                            type: "block",
+                            content: command.content,
+                            properties,
+                        }, createOptions(command.parentID));
+                }
+            }
+            case "write":
+                if (writeInput === undefined) {
+                    throw new Error("Validated write input is required");
+                }
+                if (writeInput.entity === "block" && command.parentID === undefined) {
+                    throw new CLIInputError("MISSING_OPTION", "Required option missing: --parent");
+                }
+                return writeEntity(db, writeInput.value, createOptions(command.parentID));
+            case "read":
+                return command.id === undefined
+                    ? readWorkspace(db)
+                    : readCommandEntity(db, command.id);
+            case "list":
+                return command.id === undefined
+                    ? listWorkspace(db)
+                    : listCommandEntity(db, command.id);
+            case "delete":
+                if (command.id === undefined) {
+                    throw new Error("Validated delete entity ID is required");
+                }
+                return deleteCommandEntity(db, command.id);
+            case "search":
+                return search(db, command.query, command.type);
+        }
+    }
+    catch (error) {
+        if (error instanceof CLIInputError || error instanceof CLIOperationError) {
+            throw error;
+        }
+        throw operationError("OPERATION_FAILED", error);
+    }
+    finally {
+        db.close();
+    }
+}
+function withInitializedWorkspace(name, read) {
+    let db;
+    try {
+        db = initializeWorkspace(name);
+    }
+    catch (error) {
+        throw operationError("WORKSPACE_INIT_FAILED", error, { workspace: name });
+    }
+    try {
+        return read(db);
+    }
+    finally {
+        db.close();
+    }
+}
+function readCommandEntity(db, id) {
+    switch (inferEntityType(id)) {
+        case "workspace":
+            return readMatchingWorkspace(db, id);
+        case "object":
+        case "block":
+            return readAPIEntity(db, id);
+    }
+}
+function listCommandEntity(db, id) {
+    switch (inferEntityType(id)) {
+        case "workspace":
+            readMatchingWorkspace(db, id);
+            return listWorkspace(db);
+        case "object":
+        case "block":
+            return listAPIEntity(db, id);
+    }
+}
+function deleteCommandEntity(db, id) {
+    switch (inferEntityType(id)) {
+        case "workspace":
+            throw new CLIOperationError("UNSUPPORTED_DELETE", "Workspace deletion is not supported");
+        case "object":
+        case "block":
+            return deleteAPIEntity(db, id);
+    }
+}
+function createOptions(parentID) {
+    return parentID === undefined ? {} : { parentID };
+}
+function readMatchingWorkspace(db, id) {
+    const metadata = readWorkspace(db);
+    if (metadata.id !== id) {
+        throw new CLIOperationError("WORKSPACE_ID_MISMATCH", `Workspace ID ${id} does not match the opened workspace`, { actualID: metadata.id });
+    }
+    return metadata;
+}
+function operationError(code, error, details) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new CLIOperationError(code, message, details);
+}

package/dist/CLI/errors.d.ts

@@ -0,0 +1,10 @@
+export declare class CLIInputError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export declare class CLIOperationError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}

package/dist/CLI/errors.js

@@ -0,0 +1,20 @@
+export class CLIInputError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "CLIInputError";
+        this.code = code;
+        this.details = details;
+    }
+}
+export class CLIOperationError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "CLIOperationError";
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/CLI/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+export declare function runCLI(argv: string[], read?: () => Promise<string>, isTTY?: boolean | undefined, confirm?: (prompt: string) => Promise<boolean>): Promise<{
+    exitCode: number;
+    output: unknown;
+    stream: "stdout" | "stderr";
+}>;

package/dist/CLI/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+import { parseCommand } from "./arguments.js";
+import { dispatchCommand } from "./dispatch.js";
+import { CLIInputError, CLIOperationError } from "./errors.js";
+import { confirmationDialogue, readStdin } from "./io.js";
+import { parseWriteInput } from "./json.js";
+export async function runCLI(argv, read = () => Bun.stdin.text(), isTTY = process.stdin.isTTY, confirm = (prompt) => confirmationDialogue(prompt, { isTTY })) {
+    try {
+        const command = parseCommand(argv);
+        const input = await readStdin(command.action === "write", isTTY, read);
+        const writeInput = command.action === "write" ? parseWriteInput(input) : undefined;
+        if (command.action === "delete") {
+            const target = command.id ?? command.workspace;
+            if (!await confirm(`Delete ${target}?`)) {
+                return success(false);
+            }
+        }
+        return success(dispatchCommand(command, writeInput));
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+function success(output) {
+    return { exitCode: 0, output, stream: "stdout" };
+}
+function failure(error) {
+    if (error instanceof CLIInputError) {
+        return {
+            exitCode: 2,
+            output: errorOutput(error.code, error.message, error.details),
+            stream: "stderr",
+        };
+    }
+    if (error instanceof CLIOperationError) {
+        return {
+            exitCode: 1,
+            output: errorOutput(error.code, error.message, error.details),
+            stream: "stderr",
+        };
+    }
+    return {
+        exitCode: 1,
+        output: errorOutput("INTERNAL_ERROR", error instanceof Error ? error.message : String(error)),
+        stream: "stderr",
+    };
+}
+function errorOutput(code, message, details) {
+    return {
+        error: {
+            code,
+            message,
+            ...(details === undefined ? {} : { details }),
+        },
+    };
+}
+async function main() {
+    const result = await runCLI(Bun.argv.slice(2));
+    const output = `${JSON.stringify(result.output)}\n`;
+    if (result.stream === "stdout") {
+        await Bun.write(Bun.stdout, output);
+    }
+    else {
+        await Bun.write(Bun.stderr, output);
+    }
+    process.exitCode = result.exitCode;
+}
+if (import.meta.main) {
+    await main();
+}