Repository navigation
feat(sdk): add a read-only programmatic API for workspace provenance - #41
Merged
Merged
Conversation
`@basou/sdk` was a types-only package (a single version constant). This makes it a runtime, read-only, semver-stable facade over `@basou/core`'s readers, so third-party tooling can read a workspace's `.basou/` provenance without stitching low-level core calls together and without any risk of mutating it (no writers are exposed). `openWorkspace(repoRoot, options?)` returns a `Workspace` handle. `repoRoot` is any directory holding a `.basou/` and needs no git (it is normalized to an absolute path); `resolveWorkspaceRoot(cwd)` is a git-based convenience for finding the root. The handle wraps the core readers: `manifest()`, `status()`, `listSessions()` / `getSession()`, `readEvents()` / `streamEvents()`, `listTasks()` / `getTask()`, `listApprovals()` / `getApproval()`, `stats(options?)`, and `renderHandoff()` / `renderDecisions()`. Session, task, and event lookups accept a full id or a unique prefix: a prefix that matches nothing yields null (or an empty stream), a prefix that matches more than one record throws `AmbiguousIdError`. `getApproval` takes an exact id. A missing or invalid `.basou/` throws `WorkspaceNotFoundError`. A `now` clock is injectable for deterministic reads. Read types (Session, Event, Task, WorkStatsResult, etc.) are re-exported so consumers import only from `@basou/sdk`. `BASOU_SDK_VERSION` is now 0.2.0; the package gains a `@basou/core` dependency. Robustness (from adversarial review): - `listApprovals` reports an id present in both pending/ and resolved/ once, under resolved, matching the CLI's dedupe (core `loadApproval` is resolved-first, so a stale pending file would otherwise double-report). - `openWorkspace` normalizes a relative root to an absolute path so `root` honors its documented contract. - The id-resolver error mapping matches the core resolver's exact contract strings rather than a loose substring, so an unrelated error containing "not found" is never swallowed to null. - The internal `.basou/` layout (`BasouPaths`) is not exposed on the handle, keeping the stable surface narrow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
takashi-matsuyama
force-pushed
the
feat/sdk-v0.2-read-api
branch
from
June 4, 2026 07:44
ba6cf01 to
2d33e3e
Compare
This was referenced Jun 4, 2026
takashi-matsuyama
added a commit
that referenced
this pull request
Jun 4, 2026
…s) (#43) Promote the Unreleased section to 0.6.0 and bump all four package manifests (core / cli / sdk / basou) to 0.6.0 in lockstep. Highlights since 0.5.0: - billing-grade work-measurement v2: Codex active time from real per-turn intervals, plus a machine_active_time_ms model-compute measure (#40). - @basou/sdk v0.2: a runtime, read-only programmatic API over @basou/core's readers for reading .basou/ provenance (#41). - @basou/core JSON Schema artifacts for the on-disk formats, generated from the Zod schemas and shipped under ./schemas/* (#42). Also: document the four-package lockstep bump in CONTRIBUTING, and record the 0.6.0 pre-publish dry-run tarball contents in the release checklist (core now ships its schemas/, cli ships two entry points). This commit only prepares the release; tagging v0.6.0 and the OIDC publish remain maintainer actions. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@basou/sdkv0.2 — the package gains a runtime, read-only, semver-stable programmatic API for reading a Basou workspace's.basou/provenance (it was types-only before). It is a thin, ergonomic facade over@basou/core's readers, so third-party tooling can read provenance without stitching low-level calls together and without any risk of mutating it (no writers are exposed). This is the keystone that unlocks third-party tooling and justifies the deferred schema-reference work.API
openWorkspace(repoRoot, options?) => Promise<Workspace>—repoRootis any directory holding a.basou/and needs no git (normalized to an absolute path). ThrowsWorkspaceNotFoundErrorif.basou/is missing/invalid.resolveWorkspaceRoot(cwd) => Promise<string>— git-based convenience to find the root.Workspacehandle:manifest(),status(),listSessions()/getSession(),readEvents()/streamEvents(),listTasks()/getTask(),listApprovals()/getApproval(),stats(options?),renderHandoff()/renderDecisions().null/ empty stream; multiple →AmbiguousIdError).getApprovaltakes an exact id.nowclock is injectable for deterministic reads. Read types (Session,Event,Task,WorkStatsResult, …) are re-exported so consumers import only from@basou/sdk.BASOU_SDK_VERSIONis now0.2.0.Design (operator-confirmed)
Handle-based + bare-root open; full read facade; read-only (no writers); types re-exported from
@basou/core(the SDK is the stability boundary on function signatures).Robustness (from adversarial review)
listApprovalsreports an id present in bothpending/andresolved/once, underresolved(coreloadApprovalis resolved-first; matches the CLI's dedupe).openWorkspacenormalizes a relative root to an absolute path.null..basou/layout (BasouPaths) is not exposed on the handle, keeping the stable surface narrow.Compatibility
Adds a
@basou/coredependency to the SDK. No@basou/coreschema or CLI changes. This PR branches frommainindependently of #40.Test plan
pnpm -r build && pnpm typecheck && pnpm test && pnpm lintall green (core 698 + sdk 17 + cli 414; lint clean apart from pre-existing unrelated warnings).WorkspaceNotFoundError(with cause), manifest/status, session list/get (full id, prefix, unknown→null, ambiguous→throw), events (eager + stream), tasks list/get,listApprovalsdedupe of a resolved-and-stale-pending id,getApproval(resolved-first, exact id, unknown→null),stats, handoff/decisions rendering, relative-root normalization, andnowinjection.🤖 Generated with Claude Code