TypeScript SDK¶
An asynchronous Node.js client for the local engine. Requires Node 22+, macOS or Linux, and the native CLI installed separately. This is a server-side SDK, not a browser SDK.
Install from a checkout¶
The package is not yet published to npm. Build and pack it from source:
git clone https://github.com/djsydney04/repo_maintainer.git
cd repo_maintainer/sdk/typescript
npm ci
npm pack
Then install the generated tarball in your application:
npm install /path/to/repo_maintainer/sdk/typescript/djsydney04-repo-maintainer-0.1.0.tgz
import { Maintainer } from "@djsydney04/repo-maintainer";
const maintainer = new Maintainer({ repo: "/path/to/repository" });
await maintainer.check();
const result = await maintainer.run("Fix the empty search state and add a regression test.");
console.log(result.status, result.summary);
console.log(result.artifacts.patch);
Pass task text, or omit it to use the configured task. Read a task file using
readFile from node:fs/promises and pass the resulting UTF-8 string.
Results and errors¶
Blocked work resolves to a typed RunResult. Missing binaries, configuration
errors, operational failures and incompatible protocol responses reject with
MaintainerError.
const client = new Maintainer({
repo: "/repos/app",
config: ".maintainer/work.yml",
binary: "/usr/local/bin/repo-maintainer",
});
const result = await client.run("Repair the documented bug.", { output: "/jobs/run-42" });
if (result.status === "blocked") console.log(result.blockers);
The client invokes the executable without a shell and passes the task on stdin. It inherits the worker's environment and keeps agent/check deadlines in the configuration. It does not install the engine, schedule jobs, or publish PRs.
Result fields and validation guarantees.
Configure entirely in TypeScript¶
Pass a typed object instead of a configuration filename:
import { Maintainer, type Configuration } from "@djsydney04/repo-maintainer";
const config: Configuration = {
version: 2,
agent: { allow_paid: true },
instructions: "Repair one reproducible bug with a regression test.",
editable: { source_dirs: ["src", "tests"], extensions: [".ts", ".tsx"] },
validation: {
setup: [{ name: "dependencies", command: ["npm", "ci"] }],
checks: [{ name: "tests", command: ["npm", "test"] }],
},
};
const client = new Maintainer({ repo: "/repos/app", config });
await client.check();
const result = await client.run();
No YAML file is loaded. Configuration uses the same engine schema and can include sources and official_hosts for web context. A string config still selects a file. The client sends objects and task text over stdin; it never evaluates a configuration script.