@krapht/ork 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/install-Hji6LIei.mjs

@@ -0,0 +1,259 @@
+import { Kr as placeFiles, Qr as inside, br as feedbackActions, ei as LESSON_CAP_TOKENS, ii as writePlainFile, ni as guardedBase, qr as placeFor, ri as plainPathInside, ti as estimateTokens } from "./src-BuF9Lbow.mjs";
+import path from "node:path";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { spawn } from "node:child_process";
+// ../core/src/feedback/lessons.ts
+/**
+* @file Accepting a feedback item as a lesson (specs/feedback.md, ADR-059): one
+*   line in the workflow's `.ork/lessons/<workflow>.md`, marked with the item
+*   it came from so it isn't added twice, and refused when it would take the
+*   file past the cap a session loads, or when the file, or a folder on the way
+*   to it, is a link a cloned repository could aim at the person's own files.
+*   Only a person's acceptance writes one: feedback is model output that
+*   repository content can steer.
+*/
+/** A workflow's name, as the format allows it: never a path. */
+const SLUG = /^[a-z0-9][a-z0-9._-]*$/u;
+/** A workflow's lessons file in a project. */
+const lessonsFileOf = (place, workflow) => path.join(placeFiles(place).lessons, `${workflow}.md`);
+/** What marks a lesson with its item, in the file. */
+const lessonMark = (item) => `<!-- feedback ${item.slice(0, 12)} -->`;
+/** The lesson as one list entry, its later lines indented under the first. */
+const entryOf = (text, item) => {
+	const [first = "", ...rest] = text.trim().split("\n").map((line) => line.trimEnd());
+	return [`- ${first} ${lessonMark(item)}`, ...rest.map((l) => `  ${l}`)].join("\n").concat("\n");
+};
+/** Adds a lesson to its workflow's file, or says why it can't. */
+const addLesson = (ask) => {
+	if (ask.text.trim() === "") return {
+		ok: false,
+		error: "The lesson is empty."
+	};
+	if (!SLUG.test(ask.workflow) || !plainPathInside(ask.base, ask.file)) return {
+		ok: false,
+		error: `${ask.shownAs} is a link, or behind one, or outside the project: Ork writes lessons only to a plain file there, so it wrote nothing.`
+	};
+	const current = existsSync(ask.file) ? readFileSync(ask.file, "utf8") : `# Lessons for ${ask.workflow}\n\n`;
+	if (current.includes(lessonMark(ask.item))) return {
+		ok: false,
+		error: `${ask.item.slice(0, 12)} is already a lesson in ${ask.shownAs}.`
+	};
+	const next = `${current}${current === "" || current.endsWith("\n") ? "" : "\n"}${entryOf(ask.text, ask.item)}`;
+	const tokens = estimateTokens(next);
+	if (tokens > 1500) return {
+		ok: false,
+		error: `${ask.shownAs} would be about ${tokens.toLocaleString("en")} tokens, over the ${LESSON_CAP_TOKENS.toLocaleString("en")} a session loads. Edit it to make room, then accept again.`
+	};
+	const written = writePlainFile(ask.base, ask.file, next, ask.shownAs);
+	return written.ok ? {
+		ok: true,
+		tokens
+	} : written;
+};
+// ../core/src/feedback/accept.ts
+/**
+* @file Accepting a feedback item (`ork feedback accept`, the Feedback panel):
+*   marks an item accepted and, with `--lesson`, writes it as a lesson into the
+*   lessons file of the workflow it was seen in, in the project of its newest
+*   record there (ADR-059). An `ork` item is about Ork itself, so it's never a
+*   lesson: it can be published instead.
+*/
+const listed = (names) => names.map((n) => `\`${n}\``).join(", ");
+/** The workflow a lesson is for: the one named, or the only one it was seen in. */
+const workflowFor = (item, named) => {
+	if (named !== void 0) return item.workflows.includes(named) ? {
+		ok: true,
+		workflow: named
+	} : {
+		ok: false,
+		error: `${item.id.slice(0, 12)} wasn't seen in \`${named}\`, only in ${listed(item.workflows)}.`
+	};
+	const [only, other] = item.workflows;
+	if (only === void 0) return {
+		ok: false,
+		error: `No workflow is recorded for ${item.id.slice(0, 12)}, so it has no lessons file.`
+	};
+	return other === void 0 ? {
+		ok: true,
+		workflow: only
+	} : {
+		ok: false,
+		error: `${item.id.slice(0, 12)} was seen in ${listed(item.workflows)}: name one with --workflow.`
+	};
+};
+const real = (dir) => {
+	try {
+		return realpathSync(dir);
+	} catch {
+		return path.resolve(dir);
+	}
+};
+/**
+* The project of the item's newest record (in `workflow`, when given): the
+* folder its run started in, when that's still the same project. A clone that
+* was deleted is refused, never taken for a repository above it.
+*/
+const placeOf = (store, item, workflow, registered) => {
+	const record = store.feedbackRecords(item.id).findLast((r) => workflow === void 0 || r.feedback.origin.workflow === workflow);
+	const [run] = record === void 0 ? [] : store.lookup(record.runId);
+	if (run === void 0) return {
+		ok: false,
+		error: `The runs ${item.id.slice(0, 12)} was seen in are gone, so its project isn't known.`
+	};
+	if (!existsSync(run.project)) return {
+		ok: false,
+		error: `Its project at ${run.project} is gone.`
+	};
+	const folder = path.dirname(run.file);
+	const place = placeFor(existsSync(folder) ? folder : run.project, registered);
+	return real(place.root) === real(run.project) ? {
+		ok: true,
+		place,
+		project: run.project
+	} : {
+		ok: false,
+		error: `Its project at ${run.project} isn't a project any more: Ork would take it for ${place.root}.`
+	};
+};
+/** Accepts `item`, as a lesson with `--lesson`. */
+const acceptItem = (store, item, args, registered) => {
+	const name = `${item.id.slice(0, 12)}: ${item.title}`;
+	const actions = feedbackActions(item);
+	if (!args.lesson) {
+		if (!actions.accept.ok) return {
+			ok: false,
+			error: actions.accept.error
+		};
+		store.setFeedbackStatus(item.id, "accepted");
+		return {
+			ok: true,
+			lines: [`accepted ${name}`]
+		};
+	}
+	if (!actions.lesson.ok) return {
+		ok: false,
+		error: actions.lesson.error
+	};
+	const chosen = workflowFor(item, args.workflow);
+	if (!chosen.ok) return chosen;
+	const found = placeOf(store, item, chosen.workflow, registered);
+	if (!found.ok) return found;
+	const { place } = found;
+	const file = lessonsFileOf(place, chosen.workflow);
+	const shownAs = inside(place.root, file) ? path.relative(place.root, file) : file;
+	const added = addLesson({
+		file,
+		base: guardedBase(place),
+		shownAs,
+		workflow: chosen.workflow,
+		item: item.id,
+		text: args.text ?? item.title
+	});
+	if (!added.ok) return added;
+	if (actions.accept.ok) store.setFeedbackStatus(item.id, "accepted");
+	return {
+		ok: true,
+		lesson: {
+			file: shownAs,
+			root: place.root,
+			workflow: chosen.workflow,
+			tokens: added.tokens
+		},
+		lines: [`accepted ${name}`, `lesson added to ${shownAs} in ${place.root} (about ${added.tokens.toLocaleString("en")} of ${LESSON_CAP_TOKENS.toLocaleString("en")} tokens); every session of \`${chosen.workflow}\` reads it from now on`]
+	};
+};
+const lessonPlaceOf = (store, item, workflow, registered) => {
+	const found = placeOf(store, item, workflow, registered);
+	if (!found.ok) return {
+		ok: false,
+		workflow,
+		error: found.error
+	};
+	const { place } = found;
+	const file = lessonsFileOf(place, workflow);
+	const exists = existsSync(file);
+	return {
+		ok: true,
+		workflow,
+		file: inside(place.root, file) ? path.relative(place.root, file) : file,
+		root: place.root,
+		tokens: exists ? estimateTokens(readFileSync(file, "utf8")) : 0,
+		exists
+	};
+};
+// ../core/src/remote/session.ts
+const chattable = (type) => type === "agent.leader" || type === "agent.worker";
+/** Reads `node`'s session from a run's events, and every node's last output. */
+const nodeSession = (events, node) => {
+	const session = {
+		known: false,
+		chattable: false,
+		running: false
+	};
+	const outputs = {};
+	for (const { event } of events) {
+		if (event.type === "run.started") {
+			const declared = event.nodes.find((n) => n.id === node);
+			if (declared !== void 0) {
+				session.known = true;
+				session.chattable = chattable(declared.type);
+			}
+		}
+		if (event.type === "node.finished") outputs[event.id] = event.output;
+		if (!("id" in event) || event.id !== node) continue;
+		if (event.type === "node.started") {
+			session.known = true;
+			session.chattable = chattable(event.nodeType);
+			session.running = true;
+		}
+		if (event.type === "node.finished") session.running = false;
+		if (event.type === "worktree" && event.action === "created") session.checkout = {
+			path: event.path,
+			...event.branch === void 0 ? {} : { branch: event.branch },
+			own: true,
+			owner: node
+		};
+		if (event.type !== "node.event") continue;
+		const inner = event.event;
+		if (inner.fork === true) continue;
+		if (inner.type === "session.started") {
+			session.sessionId = inner.sessionId;
+			if (inner.cwd !== void 0) session.cwd = inner.cwd;
+			if (inner.driver !== void 0) session.driver = inner.driver;
+			if (inner.model !== "") session.model = inner.model;
+		}
+		if (inner.type === "session.finished" && inner.outcome.sessionId !== "") session.sessionId = inner.outcome.sessionId;
+	}
+	return {
+		session,
+		outputs
+	};
+};
+/**
+* Runs the command; resolves its exit code. Without `onOutput` it writes on the
+* terminal.
+*/
+const runInstall = (argv, onOutput) => new Promise((resolve) => {
+	const [program = "", ...args] = argv;
+	const child = spawn(program, args, { stdio: onOutput === void 0 ? "inherit" : [
+		"ignore",
+		"pipe",
+		"pipe"
+	] });
+	for (const stream of ["stdout", "stderr"]) {
+		child[stream]?.setEncoding("utf8");
+		child[stream]?.on("data", (text) => {
+			onOutput?.(stream, text);
+		});
+	}
+	child.on("error", (error) => {
+		const line = `Could not run ${program}: ${error.message}\n`;
+		if (onOutput === void 0) process.stderr.write(line);
+		else onOutput("stderr", line);
+		resolve(127);
+	});
+	child.on("close", (code) => {
+		resolve(code ?? 1);
+	});
+});
+export { placeOf as a, lessonPlaceOf as i, nodeSession as n, acceptItem as r, runInstall as t };

package/dist/{limits-B1-DYc3d.mjs → limits-BD6RZRCS.mjs}

@@ -1,4 +1,4 @@
-import { a as limitsNow, i as NOT_STARTED, o as limitsReport, r as capsHere } from "./src-Dujmvv4s.mjs";
+import { _t as limitsReport, gt as limitsNow, ht as NOT_STARTED, v as capsHere } from "./src-BuF9Lbow.mjs";
 // src/run/limits.ts
 /**
 * @file The limits across runs that apply here (RFC-007): the user's settings
@@ -26,7 +26,7 @@ const runLimits = (store, place, home) => {
 * Whether what is left of a workflow can spend: a tool-only one, or a resume
 * with only tools to go, is not held back by a quota.
 */
-const spendsAnything = (workflow, history) => Object.entries(workflow.nodes).some(([id, node]) => (node.type === "claude.leader" || node.type === "claude.worker" || node.type === "workflow.call") && history?.get(id)?.at(-1)?.ok !== true);
+const spendsAnything = (workflow, history) => Object.entries(workflow.nodes).some(([id, node]) => (node.type === "agent.leader" || node.type === "agent.worker" || node.type === "workflow.call") && history?.get(id)?.at(-1)?.ok !== true);
 /** Why a run won't start: a settings file it can't read, or a spent limit. */
 const limitsRefusal = (limits, workflow, history) => {
 	if (!spendsAnything(workflow, history)) return [];

package/dist/{mcp-DE_EmyVm.mjs → mcp-CpbDmBLG.mjs}

@@ -1,8 +1,8 @@
-import { h as isNewer } from "./src-Dujmvv4s.mjs";
-import { n as ORK_VERSION } from "./__build_info__-fy6L1Mrd.mjs";
-import { a as openMcp, c as refused, o as tool, s as answer } from "./src-BbyEoMn4.mjs";
-import { n as explainNode } from "./context-DT8MfEIR.mjs";
-import { p as runMarkerIn } from "./src-DOcK8Jfp.mjs";
+import { T as isNewer } from "./src-BuF9Lbow.mjs";
+import { h as runMarkerIn } from "./src-k0A_QpST.mjs";
+import { n as ORK_VERSION } from "./__build_info__-0wqQ-rtf.mjs";
+import { n as explainNode } from "./context-B-fjPJky.mjs";
+import { a as openMcp, c as refused, o as tool, s as answer } from "./src-BrFfDKux.mjs";
 import { z } from "zod";
 import { defineCommand } from "citty";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -43,7 +43,7 @@ const orkMcpServer = (options = {}) => {
 		...options.script === void 0 ? {} : { script: options.script }
 	});
 	const all = [...opened.tools, explainTool(opened, options.home)];
-	const tools = options.expects !== void 0 && isNewer(options.expects, "1.0.0-alpha.2") ? tooOld(all, options.expects) : all;
+	const tools = options.expects !== void 0 && isNewer(options.expects, "1.0.0-alpha.21") ? tooOld(all, options.expects) : all;
 	const server = new McpServer({
 		name: "ork",
 		version: ORK_VERSION

package/dist/once-J8Qn5fTG.mjs

@@ -0,0 +1,112 @@
+import "./src-BuF9Lbow.mjs";
+import { n as OncePathspecError, t as runOnce } from "./run-CtuNY3mE.mjs";
+import { c as write, l as writeErr, s as style } from "./output-DXZbnFt_.mjs";
+import { t as ago } from "./format-CiPhQqbX.mjs";
+import { spawn } from "node:child_process";
+import { defineCommand, parseArgs } from "citty";
+// src/commands/once.ts
+/**
+* @file `ork once -- <command>`: runs a command unless the same check already
+*   passed on identical files, and records a pass (specs/check-once.md). The
+*   command's own output and exit code are `ork once`'s; a hit prints one line
+*   and exits 0. Everything after `--` is the command, so its flags are never
+*   Ork's.
+*/
+const args = {
+	as: {
+		type: "string",
+		description: "The check's name (default: the command's text)"
+	},
+	covers: {
+		type: "string",
+		description: "Also record the pass for this name (repeat for more)"
+	},
+	on: {
+		type: "string",
+		description: "A git pathspec the check depends on; only matching files key it (repeat for more)"
+	},
+	"with-head": {
+		type: "boolean",
+		description: "Key the check by HEAD too (for checks relative to it)"
+	},
+	force: {
+		type: "boolean",
+		description: "Run even after a pass"
+	}
+};
+/** The command's exit code: a signal or a program that can't start is 1. */
+const exitCodeOf = (command) => new Promise((resolve) => {
+	const [program = "", ...rest] = command;
+	const child = spawn(program, rest, { stdio: "inherit" });
+	child.on("error", (error) => {
+		writeErr(`Cannot run ${program}: ${error.message}`);
+		resolve(1);
+	});
+	child.on("close", (code) => {
+		resolve(code ?? 1);
+	});
+});
+/**
+* Every use of a repeatable flag, `--flag v` or `--flag=v`: citty keeps only
+* the last. Not `run.ts`'s `flagValues`, which would load the run command's
+* imports on every `ork once`.
+*/
+const valuesOf = (before, flag) => before.flatMap((arg, index) => {
+	if (arg.startsWith(`${flag}=`)) return [arg.slice(flag.length + 1)];
+	if (arg !== flag) return [];
+	const next = before[index + 1];
+	return [next === void 0 || next.startsWith("--") ? void 0 : next];
+});
+/** The values of `flag`, or `undefined` when one of its uses has none. */
+const listOf = (before, flag) => {
+	const values = valuesOf(before, flag);
+	return values.every((value) => value !== void 0 && value !== "") ? values.filter((value) => value !== void 0) : void 0;
+};
+const once = defineCommand({
+	meta: {
+		name: "once",
+		description: "Run a command unless the same check already passed on these files: ork once [flags] -- <command…>"
+	},
+	args,
+	run: async ({ rawArgs }) => {
+		const split = rawArgs.indexOf("--");
+		const command = split === -1 ? [] : rawArgs.slice(split + 1);
+		if (command.length === 0) {
+			writeErr("Say what to run after --: ork once [--as <name>] [--covers <name>]… [--on <pathspec>]… [--with-head] [--force] -- <command…>");
+			process.exitCode = 1;
+			return;
+		}
+		const before = rawArgs.slice(0, split);
+		const given = parseArgs(before, args);
+		const covers = listOf(before, "--covers");
+		const on = listOf(before, "--on");
+		if (covers === void 0 || on === void 0) {
+			writeErr(`${covers === void 0 ? "--covers needs a name" : "--on needs a pathspec"}: ork once [--covers <name>]… [--on <pathspec>]… -- <command…>`);
+			process.exitCode = 1;
+			return;
+		}
+		const run = process.env["ORK_RUN"];
+		const node = process.env["ORK_NODE"];
+		const result = await runOnce({
+			cwd: process.cwd(),
+			name: given["as"] ?? command.join(" "),
+			covers,
+			on,
+			withHead: given["with-head"] === true,
+			force: given["force"] === true,
+			...run === void 0 || node === void 0 ? {} : { who: `${run}/${node}` },
+			run: () => exitCodeOf(command)
+		}).catch((error) => {
+			if (!(error instanceof OncePathspecError)) throw error;
+			writeErr(error.message);
+			return null;
+		});
+		if (result === null) {
+			process.exitCode = 1;
+			return;
+		}
+		if (result.skipped) write(`${style("green", "✓")} check already passed on these files · ${ago(result.pass.at)} · ${result.pass.who}`);
+		process.exitCode = result.code;
+	}
+});
+export { once };

package/dist/orphan-guard-BFKg8VSd.mjs

@@ -0,0 +1,58 @@
+import { Readable, Writable } from "node:stream";
+// ../core/src/machine/orphan-guard.ts
+/**
+* @file The orphan guard: a node's processes end with `ork`, whatever ends
+*   `ork` (SIGKILL, the OOM killer, a crash exit). A child started in its own
+*   process group (`detached: true`) under `sh` also starts a small watcher in
+*   that group, which reads a pipe that only `ork` holds open. `ork` never
+*   writes to it, so when `ork` dies the read sees EOF, and the watcher sends
+*   its own group (`kill 0`, never another's) SIGTERM, then SIGKILL after
+*   {@link KILL_AFTER_MS}. A line on the pipe instead lets the watcher exit
+*   quietly, and so does killing it, which is how a node that ends normally
+*   leaves its leftover background processes alone. POSIX only. Two uses:
+*
+*   - A shell that outlives the program (the tool runner's timing wrapper):
+*     `${orphanGuard(4)} w=$!; "$0" "$@" 4<&-; s=$?; kill -s KILL $w`, then
+*     spawn with a `"pipe"` at `stdio[4]` and call
+*     `holdGuard(child.stdio[4])`.
+*   - A shell that `exec`s the program (a session, so its pid stays the
+*     driver's): `${orphanGuard(3)} exec 3<&-; exec "$0" "$@"` (a bare `exec`
+*     closes the pipe: macOS's `sh` keeps a copy of one an `exec` command
+*     closes, which the driver would inherit), with a `"pipe"` at `stdio[3]`;
+*     nothing is left to kill the watcher, so call the function `holdGuard`
+*     returns once the driver has exited (on `exit`: the pipe holds `close`).
+*/
+/** How long the group gets to end after SIGTERM before SIGKILL. */
+const KILL_AFTER_MS = 2e3;
+/** The file descriptors a redirect can name in every POSIX shell. */
+const SHELL_FDS = [
+	3,
+	4,
+	5,
+	6,
+	7,
+	8,
+	9
+];
+/**
+* Shell text that starts the watcher in the background on pipe `fd` (3 to 9);
+* it ends with `&`, so `$!` after it is the watcher's pid. The watcher holds no
+* other descriptor, so it never keeps the child's output pipes open.
+*/
+const orphanGuard = (fd) => {
+	const others = SHELL_FDS.filter((other) => other !== fd).map((other) => `${String(other)}>&-`).join(" ");
+	return `{ read -r _ork <&${String(fd)} || { trap '' TERM; kill -s TERM 0; sleep ${String(KILL_AFTER_MS / 1e3)}; kill -s KILL 0; }; } </dev/null >/dev/null 2>&1 ${others} & `;
+};
+/**
+* Keeps `ork`'s end of the watch pipe (`child.stdio[fd]`) open and drained, so
+* it never holds back the child's `close`; returns the release, which writes
+* the line that lets the watcher exit without touching its group.
+*/
+const holdGuard = (pipe) => {
+	pipe?.on("error", () => {});
+	if (pipe instanceof Readable) pipe.resume();
+	return () => {
+		if (pipe instanceof Writable && pipe.writable) pipe.write("\n");
+	};
+};
+export { holdGuard as n, orphanGuard as r, KILL_AFTER_MS as t };