@polydeukes/sdk-ts 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyung Soo Seung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,61 @@
+# `@polydeukes/sdk-ts`
+
+[English](./README.md) · **한국어**
+
+이 패키지는 TypeScript에서 약속(covenant) 입력 IR을 판정기에 건넵니다. 판정받는 프로젝트의
+`polydeukes` 설치를 찾고, 입력을 표준 입력에 넣어 `pdks covenant check`를 스폰하며, 판정
+결과를 값으로 돌려줍니다. 판정 코드는 여기에 없고 텔레메트리 행도 여기서 쓰지 않습니다. 행은
+자식 프로세스가 씁니다.
+
+`polydeukes` · `@polydeukes/core`와 함께 설치합니다. 둘 다 이 패키지의
+`peerDependencies`입니다.
+
+```sh
+pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
+```
+
+실행 파일도 설치 단계도 없습니다.
+
+<a id="overview"></a>
+## 개요
+
+공개 계약 심볼은 다음과 같습니다.
+
+- `checkCovenant`
+- `CheckCovenantSpec`
+- `CheckCovenantSpawnSpec`
+- `CheckCovenantVerdict`
+
+<a id="examples"></a>
+## 예제
+
+```ts
+import { checkCovenant } from '@polydeukes/sdk-ts';
+
+// repoRoot에서 IR을 표준 입력에 넣어 `pdks covenant check --enforce block`을 스폰합니다.
+// IR은 호출자의 것이며 이 패키지는 거기에 아무것도 더하지 않습니다.
+const verdict = await checkCovenant({
+  repoRoot: process.cwd(),
+  input: {
+    toolCalls: [{ name: 'writeFile', args: { path: 'src/index.ts' } }],
+    subagentSpawns: [],
+    userMessages: [],
+    tools: { mutating: ['writeFile', 'rm'], shell: ['exec'], commandArgs: ['command'] },
+  },
+});
+
+if (verdict.verdict === 'blocked') {
+  // `reason`은 판정기 자신의 stderr입니다. 그 텍스트를 어디에 둘지는 호출자가 정합니다.
+  console.error(verdict.reason);
+}
+```
+
+`enforce`의 기본값은 `block`입니다. 판정 결과는 `upheld` · `blocked` · `unjudged` 셋이고,
+`unjudged`는 `polydeukes`가 설치되지 않은 프로젝트와 판정 결과가 아닌 모든 자식 상태를
+포괄합니다.
+
+<a id="see-also"></a>
+## 같이 보기
+
+- [`@polydeukes/sdk-ts` 패키지 레퍼런스](../../docs/reference/packages/sdk-ts.ko.md)
+- [판정기(`covenant` 모듈)](../../docs/reference/packages/polydeukes.ko.md#covenant-module)

package/README.md

@@ -0,0 +1,60 @@
+# `@polydeukes/sdk-ts`
+
+**English** · [한국어](./README.ko.md)
+
+This package hands a covenant input IR to the judge from TypeScript. It locates the
+`polydeukes` install of the project being judged, spawns `pdks covenant check` with the input
+on stdin, and returns the verdict as a value. No judgment logic lives here, and no telemetry
+row is written here — the child process writes it.
+
+Install it next to `polydeukes` and `@polydeukes/core`, which it names as `peerDependencies`:
+
+```sh
+pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
+```
+
+There is no bin and no install step.
+
+<a id="overview"></a>
+## Overview
+
+Public contract symbols include:
+
+- `checkCovenant`
+- `CheckCovenantSpec`
+- `CheckCovenantSpawnSpec`
+- `CheckCovenantVerdict`
+
+<a id="examples"></a>
+## Examples
+
+```ts
+import { checkCovenant } from '@polydeukes/sdk-ts';
+
+// Spawns `pdks covenant check --enforce block` in repoRoot with the IR on stdin.
+// The IR is the caller's: this package adds nothing to it.
+const verdict = await checkCovenant({
+  repoRoot: process.cwd(),
+  input: {
+    toolCalls: [{ name: 'writeFile', args: { path: 'src/index.ts' } }],
+    subagentSpawns: [],
+    userMessages: [],
+    tools: { mutating: ['writeFile', 'rm'], shell: ['exec'], commandArgs: ['command'] },
+  },
+});
+
+if (verdict.verdict === 'blocked') {
+  // `reason` is the judge's own stderr — the caller decides where it goes.
+  console.error(verdict.reason);
+}
+```
+
+`enforce` defaults to `block`. The three verdicts are `upheld`, `blocked`, and `unjudged`;
+`unjudged` covers a project with no `polydeukes` installed and any child status that is not a
+verdict.
+
+<a id="see-also"></a>
+## See also
+
+- [`@polydeukes/sdk-ts` package reference](../../docs/reference/packages/sdk-ts.md)
+- [The judge (`covenant` module)](../../docs/reference/packages/polydeukes.md#covenant-module)

package/dist/check-covenant.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `checkCovenant` — hand one covenant input to `pdks covenant check` and read the verdict.
+ *
+ * The whole package: locate the umbrella in the caller's install graph, spawn its bin with
+ * the input on stdin, and turn the child's exit status and stderr into a value. Nothing
+ * here judges, records a telemetry row, or adds to the input — the branches are whether
+ * the umbrella resolved and what status the child left with.
+ */
+import type { CovenantInput } from '@polydeukes/core';
+/** What the spawn seam is handed: the executable, its arguments, its cwd, and its stdin. */
+export type CheckCovenantSpawnSpec = {
+    command: string;
+    args: string[];
+    cwd: string;
+    stdin: string;
+};
+/** `checkCovenant` input. */
+export type CheckCovenantSpec = {
+    /** The project being judged — config discovery, the child's cwd, and the install graph. */
+    repoRoot: string;
+    /** The caller's own input. The runner refuses one carrying a `world` key. */
+    input: CovenantInput;
+    /** The observer's posture for the run. ABSENT is `block`. */
+    enforce?: 'advise' | 'block';
+    /** Injected spawn seam — absent, the child runs under this process's node executable. */
+    spawn?: (spec: CheckCovenantSpawnSpec) => Promise<{
+        status: number | null;
+        stderr: string;
+    }>;
+};
+/**
+ * What the judge answered.
+ *
+ * `advisories` and `reason` are the child's stderr verbatim: an unattended caller has no
+ * terminal to read it on, so the text comes back as the value and the caller decides where
+ * it goes. `unjudged` is every status that is not a verdict — no judgment happened, and
+ * reading it as an uphold would let an uninstalled judge pass every call.
+ */
+export type CheckCovenantVerdict = {
+    verdict: 'upheld';
+    advisories: string;
+} | {
+    verdict: 'blocked';
+    reason: string;
+} | {
+    verdict: 'unjudged';
+    reason: string;
+};
+/**
+ * Judge one input against the covenants of `repoRoot` and return the verdict as a value.
+ *
+ * The input travels verbatim; this package neither reads nor completes it.
+ */
+export declare function checkCovenant(spec: CheckCovenantSpec): Promise<CheckCovenantVerdict>;

package/dist/check-covenant.js

@@ -0,0 +1,85 @@
+/**
+ * `checkCovenant` — hand one covenant input to `pdks covenant check` and read the verdict.
+ *
+ * The whole package: locate the umbrella in the caller's install graph, spawn its bin with
+ * the input on stdin, and turn the child's exit status and stderr into a value. Nothing
+ * here judges, records a telemetry row, or adds to the input — the branches are whether
+ * the umbrella resolved and what status the child left with.
+ */
+import { spawn as spawnChild } from 'node:child_process';
+import { findUmbrellaBin, UMBRELLA_PACKAGE } from './resolve-umbrella.js';
+/** The judge's own subcommand — the caller's input goes to its stdin. */
+const CHECK_ARGS = ['covenant', 'check', '--enforce'];
+/**
+ * Run the bin under this process's node executable, collect stderr, and discard stdout.
+ *
+ * No file descriptor is inherited: a caller may hold none of its own, and an inherited
+ * stdout that is closed kills the child with EPIPE before it can answer.
+ */
+function defaultSpawn(spec) {
+    return new Promise((resolve, reject) => {
+        const child = spawnChild(spec.command, spec.args, {
+            cwd: spec.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stderr = '';
+        child.stderr.setEncoding('utf-8');
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        // Drained and dropped: the judge writes no verdict to stdout, and an unread pipe
+        // fills and stalls the child.
+        child.stdout.resume();
+        child.on('error', reject);
+        child.on('close', (status) => {
+            resolve({ status, stderr });
+        });
+        // A child that exits before draining stdin raises EPIPE on this stream; the exit status
+        // is the answer, and an unheard stream error would end the caller's process instead.
+        child.stdin.on('error', () => { });
+        child.stdin.end(spec.stdin);
+    });
+}
+/**
+ * Judge one input against the covenants of `repoRoot` and return the verdict as a value.
+ *
+ * The input travels verbatim; this package neither reads nor completes it.
+ */
+export async function checkCovenant(spec) {
+    const bin = findUmbrellaBin(spec.repoRoot);
+    if (bin === undefined) {
+        return {
+            verdict: 'unjudged',
+            reason: `no ${UMBRELLA_PACKAGE} in the install graph of ${spec.repoRoot}: install it to have this input judged`,
+        };
+    }
+    const spawn = spec.spawn ?? defaultSpawn;
+    let status;
+    let stderr;
+    try {
+        ({ status, stderr } = await spawn({
+            command: process.execPath,
+            args: [bin, ...CHECK_ARGS, spec.enforce ?? 'block'],
+            cwd: spec.repoRoot,
+            stdin: JSON.stringify(spec.input),
+        }));
+    }
+    catch (error) {
+        // No process ran, so no verdict and no row: the failure comes back as the value the
+        // caller was promised rather than as an exception it did not sign up for.
+        return {
+            verdict: 'unjudged',
+            reason: `the judge could not be spawned: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (status === 0)
+        return { verdict: 'upheld', advisories: stderr };
+    if (status === 2)
+        return { verdict: 'blocked', reason: stderr };
+    return {
+        verdict: 'unjudged',
+        reason: status === null
+            ? 'the judge was killed by a signal before it answered'
+            : `the judge exited with status ${status} instead of a verdict`,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @polydeukes/sdk-ts — hand a covenant input to `pdks covenant check` from TypeScript.
+ *
+ * Alpha. One verb: it locates the `polydeukes` install of the project being judged, spawns
+ * its bin, and returns the verdict as a value. No judgment logic lives here.
+ * See https://github.com/huskyhoochu/polydeukes
+ */
+export { type CheckCovenantSpawnSpec, type CheckCovenantSpec, type CheckCovenantVerdict, checkCovenant, } from './check-covenant.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @polydeukes/sdk-ts — hand a covenant input to `pdks covenant check` from TypeScript.
+ *
+ * Alpha. One verb: it locates the `polydeukes` install of the project being judged, spawns
+ * its bin, and returns the verdict as a value. No judgment logic lives here.
+ * See https://github.com/huskyhoochu/polydeukes
+ */
+export { checkCovenant, } from './check-covenant.js';

package/dist/resolve-umbrella.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Locating the `polydeukes` install this SDK spawns the judge from.
+ *
+ * The anchor is the project root the caller named, never this module's own location:
+ * anchoring here would answer for the graph THIS package was installed into, which is a
+ * different tree from the one being judged.
+ */
+/** The umbrella package the spawn looks for. */
+export declare const UMBRELLA_PACKAGE = "polydeukes";
+/**
+ * The absolute path of the umbrella's `pdks` bin as reachable from `projectRoot`, or
+ * `undefined` when there is nothing to spawn.
+ *
+ * `findPackageJSON` is experimental in Node 24, so its behaviour can still change.
+ *
+ * A manifest found but carrying no `bin.pdks` answers `undefined` too: spawning `node
+ * undefined` crashes with no verdict and no row, which reads to the caller as the same
+ * absence reached without saying so.
+ */
+export declare function findUmbrellaBin(projectRoot: string): string | undefined;

package/dist/resolve-umbrella.js

@@ -0,0 +1,48 @@
+/**
+ * Locating the `polydeukes` install this SDK spawns the judge from.
+ *
+ * The anchor is the project root the caller named, never this module's own location:
+ * anchoring here would answer for the graph THIS package was installed into, which is a
+ * different tree from the one being judged.
+ */
+import { readFileSync } from 'node:fs';
+import { findPackageJSON } from 'node:module';
+import { join } from 'node:path';
+import { isPlainObject } from '@polydeukes/core';
+/** The umbrella package the spawn looks for. */
+export const UMBRELLA_PACKAGE = 'polydeukes';
+/**
+ * The absolute path of the umbrella's `pdks` bin as reachable from `projectRoot`, or
+ * `undefined` when there is nothing to spawn.
+ *
+ * `findPackageJSON` is experimental in Node 24, so its behaviour can still change.
+ *
+ * A manifest found but carrying no `bin.pdks` answers `undefined` too: spawning `node
+ * undefined` crashes with no verdict and no row, which reads to the caller as the same
+ * absence reached without saying so.
+ */
+export function findUmbrellaBin(projectRoot) {
+    let manifestPath;
+    try {
+        // Absence throws here rather than returning undefined (Node 24.18); the branch below
+        // covers the documented `string | undefined` return.
+        manifestPath = findPackageJSON(UMBRELLA_PACKAGE, join(projectRoot, 'package.json'));
+    }
+    catch {
+        return undefined;
+    }
+    if (manifestPath === undefined)
+        return undefined;
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+    const bin = isPlainObject(manifest) ? manifest.bin : undefined;
+    const pdks = isPlainObject(bin) ? bin.pdks : undefined;
+    if (typeof pdks !== 'string')
+        return undefined;
+    return join(manifestPath, '..', pdks);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@polydeukes/sdk-ts",
+  "version": "0.7.1",
+  "description": "Polydeukes SDK for TypeScript — one verb that hands a covenant input IR to `pdks covenant check` and returns the verdict as a value. Alpha.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huskyhoochu/polydeukes.git",
+    "directory": "packages/sdk-ts"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "7.0.2",
+    "vitest": "^5.0.0",
+    "@polydeukes/core": "^0.7.1"
+  },
+  "peerDependencies": {
+    "@polydeukes/core": "^0.7.1",
+    "polydeukes": "^0.7.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}