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

package/dist/context-B-fjPJky.mjs

@@ -0,0 +1,106 @@
+import { bt as explainSession, ei as LESSON_CAP_TOKENS } from "./src-BuF9Lbow.mjs";
+import { c as write, s as style } from "./output-DXZbnFt_.mjs";
+import { a as refusedBuiltin, s as workflowArg } from "./workflows-QLjBhGNS.mjs";
+import { a as formatReport, t as loadWorkflow } from "./validate-_HjACtk9.mjs";
+import { defineCommand } from "citty";
+// src/commands/context.ts
+/**
+* @file `ork context explain <wf> <node>`: what one node's session would load,
+*   layer by layer, as core's `explainSession` plans it without writing
+*   anything (one of Ork's own `ork:` workflows is written into the project's
+*   run folder first, as `ork run` does): its project instructions, every skill
+*   with the layer it came from and whether it is live, shadowed or switched
+*   off, its context files, its practices, and estimated tokens.
+*/
+/** Loads a workflow file and plans one node's session in it, in place. */
+const explainNode = (file, nodeId, cwd, home) => {
+	const { report, workflow, graph, place, workflowDir } = loadWorkflow(file, cwd, home);
+	if (workflow === null) return {
+		ok: false,
+		lines: formatReport(report)
+	};
+	const result = explainSession(workflow, graph, nodeId, {
+		root: place.root,
+		orkDir: place.dir,
+		workflowDir,
+		...home === void 0 ? {} : { home }
+	});
+	return result.ok ? result : {
+		ok: false,
+		lines: [result.error]
+	};
+};
+const approx = (count) => style("dim", `≈${count.toLocaleString("en")} tokens`);
+const formatExplanation = (e) => {
+	const width = Math.max(8, ...e.skills.map((s) => s.name.length));
+	const sourceWidth = Math.max(0, ...e.skills.map((s) => s.source.length));
+	const lines = [
+		`${style("bold", e.node)} ${style("dim", `(${e.type}) in ${e.workflow}`)}${e.template === void 0 ? "" : style("dim", `, planned as ${e.template}, the node it was spawned from`)}`,
+		"",
+		...e.agent === void 0 ? [] : [`${style("bold", "Agent")}  ${e.agent.name} ${style("dim", `(${e.agent.where})`)}  ${approx(e.agent.tokens)}`],
+		`${style("bold", "Instructions")}  ${e.instructions}`,
+		"",
+		style("bold", "Skills")
+	];
+	if (e.skills.length === 0) lines.push(style("dim", "  none"));
+	for (const s of e.skills) {
+		const mark = s.state === "live" ? style("green", "✓") : style("dim", "−");
+		const state = s.why === void 0 ? approx(s.tokens).replace("tokens", "tokens when used") : style("yellow", `off: ${s.why}`);
+		lines.push(`  ${mark} ${s.name.padEnd(width)}  ${s.layer.padEnd(8)}  ${style("dim", s.source.padEnd(sourceWidth))}  ${state}`);
+	}
+	lines.push("", style("bold", "Context files"));
+	if (e.files.length === 0) lines.push(style("dim", "  none"));
+	for (const f of e.files) {
+		const cut = f.cutFrom === void 0 ? "" : `  ${style("yellow", `cut at the ${LESSON_CAP_TOKENS.toLocaleString("en")}-token cap; the whole file is ${approx(f.cutFrom)}`)}`;
+		lines.push(`  ${f.layer.padEnd(8)}  ${f.name}  ${approx(f.tokens)}${cut}`);
+	}
+	lines.push("", style("bold", "Practices"));
+	for (const p of e.practices) lines.push(`  ${p.name.padEnd(8)}  ${approx(p.tokens)}`);
+	for (const name of e.skippedPractices) lines.push(`  ${name.padEnd(8)}  ${style("dim", "the project's own skill wins")}`);
+	if (e.practices.length === 0 && e.skippedPractices.length === 0) lines.push(style("dim", "  off"));
+	lines.push("", `Appended to Claude Code's system prompt: ${approx(e.appendedTokens)}`);
+	return lines;
+};
+const explain = defineCommand({
+	meta: {
+		name: "explain",
+		description: "Show what one node's session loads, layer by layer"
+	},
+	args: {
+		workflow: {
+			type: "positional",
+			description: "A workflow file, the name of one in the project's workflows (.ork/workflows/), or one of Ork's own (ork:feedback-apply)",
+			required: true
+		},
+		node: {
+			type: "positional",
+			description: "Node id",
+			required: true
+		},
+		json: {
+			type: "boolean",
+			description: "Print JSON",
+			default: false
+		}
+	},
+	run: ({ args }) => {
+		const cwd = process.cwd();
+		if (refusedBuiltin([args.workflow], cwd)) return;
+		const result = explainNode(workflowArg(args.workflow, cwd).file, args.node, cwd);
+		if (!result.ok) {
+			for (const line of result.lines) process.stderr.write(`${line}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		if (args.json) write(JSON.stringify(result.explanation, void 0, 2));
+		else for (const line of formatExplanation(result.explanation)) write(line);
+	}
+});
+const context = defineCommand({
+	meta: {
+		name: "context",
+		description: "Inspect the context Ork compiles for each node"
+	},
+	subCommands: { explain }
+});
+export { explainNode as n, context as t };

package/dist/context-DMK0U1w0.mjs

@@ -0,0 +1,160 @@
+import { $n as findFollowUp, Kr as placeFiles, Pn as liveStatus, Sn as deliverFollowUp, Yn as loadProject, gr as runGh, vn as checkFollowUpsDue } from "./src-BuF9Lbow.mjs";
+// ../core/src/follow-ups/take.ts
+const put = (rows, f, run, at) => {
+	const next = {
+		...f,
+		takenBy: run,
+		updatedAt: at
+	};
+	rows.putFollowUp(next);
+	return next;
+};
+/**
+* Why `f` is held by the run that took it, as the end of `taken by run <id>,
+* <note>`; `undefined` when it is free. A run the store does not know counts as
+* live while the mark is recent, so a run that fails its preflight frees its
+* follow-ups when the window ends.
+*/
+const heldNote = (f, isLive, now) => {
+	if (f.takenBy === void 0) return void 0;
+	const live = isLive(f.takenBy);
+	if (live !== void 0) return live ? "still running" : void 0;
+	return now - Date.parse(f.updatedAt) < 12e4 ? "not started yet; free in under 2 minutes" : void 0;
+};
+/** Whether another run holds `f`: it is not free to take again. */
+const heldByLive = (f, run, isLive, now) => f.takenBy !== run && heldNote(f, isLive, now) !== void 0;
+/**
+* The project's due `agent` follow-ups no live run has taken (`ids`), and those
+* a live run holds (`held`), so a second `--follow-ups due` doesn't take them
+* twice.
+*/
+const availableDue = (rows, project, isLive, run = "", now = () => (/* @__PURE__ */ new Date()).toISOString()) => {
+	const at = Date.parse(now());
+	const due = rows.followUps(project).filter((f) => f.for === "agent" && f.status === "due");
+	return {
+		ids: due.filter((f) => !heldByLive(f, run, isLive, at)).map((f) => f.id),
+		held: due.filter((f) => heldByLive(f, run, isLive, at))
+	};
+};
+/**
+* `ork run start --follow-ups <ids>`: the open `agent` follow-ups among `ids`
+* become `run`'s brief; why each other id wasn't taken. One a live run took is
+* refused; one a finished, failed or crashed run took can be taken again.
+*/
+const takeFollowUps = (rows, taking, now = () => (/* @__PURE__ */ new Date()).toISOString()) => {
+	const taken = [];
+	const refused = [];
+	const at = Date.parse(now());
+	for (const id of taking.ids) {
+		const f = rows.followUp(taking.project, id);
+		if (f === void 0) refused.push(`${id}: there is no such follow-up`);
+		else if (f.for !== "agent") refused.push(`${id}: it is for ${f.for}`);
+		else if (f.status === "done" || f.status === "dropped") refused.push(`${id}: it is ${f.status}`);
+		else {
+			const note = f.takenBy === taking.run ? void 0 : heldNote(f, taking.isLive, at);
+			if (note === void 0) taken.push(put(rows, f, taking.run, now()));
+			else refused.push(`${id}: taken by run ${f.takenBy}, ${note}`);
+		}
+	}
+	return {
+		taken,
+		refused
+	};
+};
+// src/follow-ups/context.ts
+/**
+* @file What `ork follow-ups` and a run share: the project's `followUps` rule,
+*   the sink a run hands its sessions' `follow_up` tool, the due check that
+*   runs before every call (a `gh` that fails only warns), and the follow-ups
+*   `ork run --follow-ups` takes as a run's brief.
+*/
+/** The project's `followUps` rule, when it sets one. */
+const followUpsRule = (place) => loadProject(place.root, placeFiles(place).rules).project?.followUps;
+/** What a run hands its sessions: each `follow_up` call, kept as the rule says. */
+const followUpSink = (options) => (input, at) => {
+	const rule = followUpsRule(options.place);
+	return deliverFollowUp(input, {
+		store: options.store,
+		project: options.place.root,
+		worktree: at.cwd,
+		...rule === void 0 ? {} : { rule },
+		...options.home === void 0 ? {} : { home: options.home },
+		...options.gh === void 0 ? {} : { gh: options.gh }
+	});
+};
+/** Gh's own words when it has no login. */
+const SIGNED_OUT = /not logged in|gh auth login/iu;
+/**
+* A gh error's first line, without a trailing period, so the notice is one
+* line.
+*/
+const oneLine = (error) => (error.trim().split("\n")[0] ?? "").trim().replace(/\.$/u, "");
+/**
+* Moves the project's follow-ups whose time has come to due, as every `ork
+* follow-ups` call does first. `gh` failing only warns, through `warn`: one
+* line per call, however many refs failed.
+*/
+const refreshDue = async (store, project, warn, gh = runGh) => {
+	try {
+		const checked = await checkFollowUpsDue({
+			rows: store,
+			project,
+			gh
+		});
+		const [first] = checked.errors;
+		if (first !== void 0) warn(checked.errors.some((error) => SIGNED_OUT.test(error)) ? "Can't check PRs: `gh` isn't signed in. After-merge follow-ups stay waiting; run `gh auth login` yourself." : `Can't check PRs: ${oneLine(first)}. After-merge follow-ups stay waiting.`);
+		return checked.due;
+	} catch (error) {
+		warn(`couldn't check what is due: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	}
+};
+/** The text a run starts from when it takes these follow-ups as its brief. */
+const briefOf = (followUps) => ["Do these follow-ups left by earlier changes:", ...followUps.flatMap((f) => [
+	"",
+	`## ${f.title} (${f.id})`,
+	...f.body === "" ? [] : [f.body],
+	...f.where.length === 0 ? [] : [`Files: ${f.where.join(", ")}`]
+])].join("\n");
+/**
+* Whether a run is going, as `ork ps` decides: running with its process alive.
+* `undefined` for a run the store does not know yet: core holds its mark for a
+* short while, as the run may be about to begin.
+*/
+const runIsLive = (store) => (runId) => {
+	const [run] = store.lookup(runId);
+	return run === void 0 ? void 0 : liveStatus(run) === "running";
+};
+const nothing = () => {};
+/**
+* The follow-ups `ids` (or prefixes) name, when every one can be taken as a
+* brief; nothing is written, so a run that fails to start leaves them alone.
+*/
+const checkTakeable = (store, project, ids) => {
+	const full = [];
+	const lines = [];
+	for (const id of ids) {
+		const found = findFollowUp(store, project, id);
+		if (found.ok) full.push(found.followUp.id);
+		else lines.push(found.error);
+	}
+	const { taken, refused } = takeFollowUps({
+		followUp: (p, id) => store.followUp(p, id),
+		followUps: (p) => store.followUps(p),
+		putFollowUp: nothing
+	}, {
+		project,
+		run: "",
+		ids: full,
+		isLive: runIsLive(store)
+	});
+	const all = [...lines, ...refused];
+	return all.length > 0 ? {
+		ok: false,
+		lines: all.map((line) => `--follow-ups: ${line}`)
+	} : {
+		ok: true,
+		followUps: taken
+	};
+};
+export { refreshDue as a, heldNote as c, followUpsRule as i, takeFollowUps as l, checkTakeable as n, runIsLive as o, followUpSink as r, availableDue as s, briefOf as t };

package/dist/detached-q0AYG0Bs.mjs

@@ -0,0 +1,39 @@
+import { pt as detachRun } from "./src-BuF9Lbow.mjs";
+import { n as newRunId } from "./find-Ct5CNl1J.mjs";
+import { c as write, i as detachHint, l as writeErr, s as style } from "./output-DXZbnFt_.mjs";
+import { r as isFlag } from "./short-flags-Qf21as0E.mjs";
+// src/run/detached.ts
+/**
+* @file `ork run --detach`: checks what the run would refuse (a `--follow-ups`
+*   that can't be taken) before any run folder is made, then starts the run in
+*   the background and says how to follow it.
+*/
+/** Starts the run in the background; `rawArgs` are `ork run`'s own, as typed. */
+const startDetached = async (store, options) => {
+	const { rawArgs, cwd, target } = options;
+	const { prepareFollowUps } = await import("./brief-C2hew8cS.mjs");
+	if (await prepareFollowUps(store, rawArgs, void 0, target, void 0, false) === void 0) return;
+	const single = options.node !== void 0 && options.node !== "";
+	const runId = newRunId(store, single ? "node-" : "");
+	const detached = await detachRun({
+		store,
+		runId,
+		args: [
+			"run",
+			...rawArgs.filter((arg) => !isFlag(arg, "detach")),
+			"--run-id",
+			runId
+		],
+		cwd,
+		runDir: target.runDir(runId)
+	});
+	if (detached.ok) {
+		write(`▸ run ${detached.runId} started in the background`);
+		write(style("dim", `  ${detachHint(detached.runId)}`));
+	} else {
+		writeErr(detached.error);
+		writeErr(style("dim", `(output: ${detached.log})`));
+		process.exitCode = 1;
+	}
+};
+export { startDetached };

package/dist/extra-arguments-BxQMXARO.mjs

@@ -0,0 +1,13 @@
+import { n as argsOf } from "./command-tree-CEkzWNy6.mjs";
+import { t as argumentError } from "./argument-error-CihH46Le.mjs";
+// src/extra-arguments.ts
+/** Refuses the first word beyond the positionals the command declares. */
+const refuseExtraArguments = {
+	name: "refuse-extra-arguments",
+	setup: async ({ cmd, args }) => {
+		const declared = Object.values(await argsOf(cmd)).filter((def) => def.type === "positional").length;
+		const extra = args._[declared];
+		if (extra !== void 0) throw argumentError(`Unexpected argument \`${extra}\`.`);
+	}
+};
+export { refuseExtraArguments as t };

package/dist/{find-D6Gj1sxg.mjs → find-Ct5CNl1J.mjs}

@@ -1,4 +1,4 @@
-import { xn as placeFor } from "./src-Dujmvv4s.mjs";
+import { qr as placeFor } from "./src-BuF9Lbow.mjs";
 import { randomUUID } from "node:crypto";
 // ../core/src/remote/find.ts
 /**
@@ -16,7 +16,7 @@ const findRun = (store, arg, cwd) => {
 		});
 		return latest === void 0 ? {
 			ok: false,
-			error: "No runs in this project yet; see `ork ps --all`."
+			error: "No runs in this project yet; see `ork ps --project all`."
 		} : {
 			ok: true,
 			run: latest

package/dist/flags-C90N4J1i.mjs

@@ -0,0 +1,145 @@
+import { qr as placeFor } from "./src-BuF9Lbow.mjs";
+import { i as parseLimit, n as unknownProjectRefusal, r as parseFilters, t as limitRefusal } from "./refusals-DQQX3AIb.mjs";
+import { t as findRun } from "./find-Ct5CNl1J.mjs";
+import { a as resolved, n as argsOf } from "./command-tree-CEkzWNy6.mjs";
+import { l as writeErr } from "./output-DXZbnFt_.mjs";
+import { t as argumentError } from "./argument-error-CihH46Le.mjs";
+// src/list/known-flags.ts
+/** Names citty reads without the command declaring them. */
+const BUILT_IN = /* @__PURE__ */ new Set([
+	"_",
+	"help",
+	"h"
+]);
+/** A flag's name without its spelling: `run-id`, `runId` and `run_id` agree. */
+const spelling = (name) => name.replaceAll(/[-_]/gu, "").toLowerCase();
+/** How the flag is typed: `--since`, or `-x` for a one-letter name. */
+const written = (name) => name.length === 1 ? `-${name}` : `--${name}`;
+/** Refuses the first flag the command does not declare. */
+const refuseUnknownFlags = {
+	name: "refuse-unknown-flags",
+	setup: async ({ cmd, rawArgs, args }) => {
+		const [first] = rawArgs;
+		const subs = await resolved(cmd.subCommands ?? {});
+		if (first !== void 0 && first in subs) return;
+		const known = /* @__PURE__ */ new Set();
+		for (const [name, def] of Object.entries(await argsOf(cmd))) {
+			known.add(spelling(name));
+			if ("alias" in def && def.alias !== void 0) for (const alias of [def.alias].flat()) known.add(spelling(alias));
+		}
+		const unknown = Object.keys(args).find((key) => !BUILT_IN.has(key) && !known.has(spelling(key)));
+		if (unknown !== void 0) throw argumentError(`Unknown flag \`${written(unknown)}\`.`);
+	}
+};
+// src/list/flags.ts
+/**
+* @file The flags every list command shares (RFC-017), made from its field
+*   table: one flag per field (an enum field's values as citty `options`, so
+*   `--help` and Tab completion read them), `--ids`, `--limit` and `--json`;
+*   and reading them back: each value checked by core's `parseFilters`,
+*   `--limit` a positive whole number, `--project` a registered one. A refusal
+*   says why on stderr and sets the exit code; the command then returns.
+*/
+const fieldArg = (field) => {
+	if (field.type !== "enum") return {
+		type: "string",
+		description: field.description
+	};
+	return {
+		type: "enum",
+		options: [...field.values ?? [], ...field.all === true ? ["all"] : []],
+		description: field.description
+	};
+};
+/** The citty flags of `table`, then `--ids`, `--limit`, `--json`, `extra`. */
+const filterArgs = (table, options = {}) => ({
+	...Object.fromEntries(table.fields.map((field) => [field.name, fieldArg(field)])),
+	...options.ids ?? table.id !== void 0 ? { ids: {
+		type: "boolean",
+		description: "Print only the ids, comma-separated, on one line",
+		default: false
+	} } : {},
+	...options.limit ?? true ? { limit: {
+		type: "string",
+		description: "Show at most this many (a positive whole number)"
+	} } : {},
+	...options.json ?? true ? { json: {
+		type: "boolean",
+		description: "Print JSON",
+		default: false
+	} } : {},
+	...options.extra
+});
+/** Says why, and makes the command exit 1. */
+const fail = (message) => {
+	writeErr(message);
+	process.exitCode = 1;
+};
+/** The `--ids` with `--json` refusal; `true` when `args` has both. */
+const refuseIdsWithJson = (args) => {
+	if (args.ids !== true || args.json !== true) return false;
+	fail("--ids and --json can't be used together.");
+	return true;
+};
+/**
+* `args` (a command's parsed flags) read against `table`: the filter, and the
+* limit. `undefined` when something was refused (already said, exit code set).
+*/
+const readListArgs = (table, args, options = {}) => {
+	if (refuseIdsWithJson(args)) return void 0;
+	const parsed = parseFilters(table, args, options.now ?? Date.now());
+	if (!parsed.ok) {
+		fail(parsed.error);
+		return;
+	}
+	const text = args["limit"];
+	if (typeof text !== "string") return {
+		filter: parsed.filter,
+		limit: void 0
+	};
+	const limit = parseLimit(text);
+	if (limit === null) {
+		fail(limitRefusal(text));
+		return;
+	}
+	return {
+		filter: parsed.filter,
+		limit
+	};
+};
+/** The project root a scope other than `all` names. */
+const rootOf = (scope, projects) => scope === "here" ? placeFor(process.cwd(), projects).root : scope.root;
+/**
+* The scope the filter's `project` names, checked against the registered
+* projects (core does not know them): an id or a root, or `all`; none given is
+* `here`. A project not registered is refused, listing the registered ones
+* (said, exit code set, `undefined`).
+*/
+const projectScope = (filter, projects) => {
+	const key = filter["project"];
+	if (key === void 0) return "here";
+	if (key === "all") return "all";
+	const found = projects.find((p) => p.id === key || p.root === key);
+	if (found !== void 0) return { root: found.root };
+	fail(unknownProjectRefusal(key, projects.map((p) => p.id)));
+};
+/**
+* `filter` with its `run` (a prefix) made the full id of the run it names, as
+* `ork decide --run` reads it; an unknown or ambiguous run is refused with
+* `findRun`'s message (said, exit code set, `undefined`). No `run` (or an empty
+* one) leaves `filter` as it is.
+*/
+const resolveRun = (store, filter) => {
+	const run = filter["run"];
+	if (run === void 0 || run === "") return filter;
+	const found = findRun(store, run, process.cwd());
+	if (!found.ok) {
+		fail(found.error);
+		return;
+	}
+	return {
+		...filter,
+		run: found.run.id
+	};
+};
+export { refuseIdsWithJson as a, refuseUnknownFlags as c, readListArgs as i, filterArgs as n, resolveRun as o, projectScope as r, rootOf as s, fail as t };