Use Folderbase from TypeScript

@folderbase/sdk is a zero-runtime-dependency adapter for the public Folderbase Core executable. It gives Node.js apps and agent harnesses typed process supervision while Core remains the only filesystem and database authority.

Install the adapter and executable

npm install @folderbase/sdk @folderbase/cli

@folderbase/sdk does not bundle Core. The default executable name is folderbase, so it works with the npm launcher, Homebrew, Cargo, a GitHub binary, or any independently conforming implementation on PATH.

Use an explicit binary when reproducibility matters:

import { FolderbaseClient } from "@folderbase/sdk";

const folderbase = new FolderbaseClient({
  executable: "/opt/folderbase/bin/folderbase",
  timeoutMs: 30_000,
});

const contract = await folderbase.contract();
if (contract.kind !== "success") throw new Error("Core needs attention");
console.log(contract.document.capabilities);

Turn an ordinary folder into a Folderbase

const root = "/absolute/path/to/project";

const preview = await folderbase.init(root, { dryRun: true });
if (preview.kind !== "success") throw new Error("Initialization needs attention");

const initialized = await folderbase.init(root, {
  expectedPlanDigest: preview.document.plan_digest.digest,
});

The same folder can contain repositories, Markdown, PDFs, CSVs, SQLite databases, videos, design assets, and unknown regular-file formats. The SDK does not convert or upload them. It delegates to Core, which inventories metadata first and preserves the ordinary bytes.

Query live metadata

const result = await folderbase.query(root, {
  format: "folderbase-query-request-v1",
  scope: { kind: "live" },
  page: { limit: 100 },
});

if (result.kind === "success") {
  for (const entry of result.document.entries) {
    console.log(entry.path, entry.kind, entry.bytes);
  }
}

Exit 1 resolves as kind: "attention"; it is not thrown away as an exception. Exit 2, malformed output, timeouts, cancellation, and output overflow use distinct exported error classes.

Keep one active root fresh

Use the daemon only after capability discovery advertises folderbase.daemon-stdio@0.1.0:

const session = await folderbase.startDaemon(root);

session.on("event", async (hint) => {
  // Hints never contain authoritative file patches. Query Core again.
  console.log(hint.event);
});

await session.request("subscribe");
const response = await session.request("query", {
  format: "folderbase-query-request-v1",
  scope: { kind: "live" },
  page: { limit: 100 },
});

await session.shutdown();

Daemon 0.1 is serial. Cancelling an active request ends the session instead of claiming cooperative mid-request cancellation that Core does not advertise.

Bind an exact folder before first share

After capability discovery advertises folderbase.folder-scope-evidence@0.1.0, observe the exact selected ordinary folder through Core:

const evidence = await folderbase.observeFolderScope(
  "/absolute/path/to/folderbase",
  "clients/project-2",
);

console.log(evidence.document.event_id);
console.log(evidence.document.nested_boundaries);

The adapter invokes folderbase folder-scope observe ROOT SELECTED_PATH --json and validates the known v0.1 fields while preserving additive fields for forward compatibility. It never derives identity by reading .folderbase, walking the tree, or interpreting an inode. The exact implementation conformance schema remains closed. The result is local continuity evidence, not a share grant or Cloud credential. See the Folder Scope evidence reference. The result contains at most 256 nested boundaries; larger topologies preserve Core's typed folder_scope_limit_exceeded error.

Reconstruct a retained Version into a new root

After capability discovery advertises folderbase.root-reconstruction@0.1.0, use the typed helper with an explicit package, absent destination, operation ID, and exact encoded package-index digest:

const outcome = await folderbase.reconstruct(
  "/absolute/path/to/reconstruction-package",
  "/absolute/path/to/new-folderbase",
  {
    format: "folderbase-root-reconstruction-request-v1",
    operation_id: "reconstruction_019f0000-0000-7000-8000-000000000001",
    package_index_sha256: "0123456789abcdef".repeat(4),
  },
);

if (outcome.kind === "attention") {
  console.log(outcome.document.attention.code);
} else {
  console.log(outcome.document.root_attestation);
}

The SDK invokes folderbase reconstruct SOURCE DESTINATION --stdin --json, bounds the process and its output, and validates the closed result or attention document. Typed exit-2 documents remain available through FolderbaseOperationalError.

Core reconstructs ordinary files of every type as opaque bytes and publishes only an absent root after exact verification. It does not overwrite or merge an existing folder. Provider authorization, package transport, Cloud session state, and synchronization into an existing root remain separate concerns. See the root reconstruction reference for the package, replay, and conformance contract.

Use the universal surface from remote VMs

A Codex-, Claude-, or Cursor-style VM can install a pinned Core binary plus @folderbase/sdk, materialize an authorized ordinary folder, and use the same CLI JSON and Change Set contracts as a local app. Cloud authentication, share-link grants, and file transport remain separate from the database Core.

Read the process adapter contract, query/index reference, and Change Set guide before building a long-lived integration. Use root reconstruction for an absent complete root and Change Sets for scoped work against an existing Folderbase; neither operation is a Cloud sync protocol.