@krapht/ork 0.2.0 → 0.4.0

package/dist/clean-Dcr807be.mjs

@@ -0,0 +1,88 @@
+import { E as removeWorktree, O as gitOk } from "./src-CGqMati3.mjs";
+// ../core/src/worktree/clean.ts
+/**
+* @file What `ork worktrees clean` and `ork worktrees remove` do with what
+*   list.ts reads: the plan (what goes, what's kept and why), by one rule for
+*   every caller, and carrying it out. The CLI and the Worktrees panel both
+*   plan here, so neither removes what the other would keep.
+*/
+/** What names an item for `remove`: its branch, or its worktree's path. */
+const keyOf = (item) => item.branch ?? item.path ?? `${item.runId}/${item.nodeId}`;
+/** The reasons no `force` overrides: removing would break something. */
+const MAIN_CHECKOUT = "checked out in the main checkout";
+const RUN_GOING = "its run is still going";
+const kept = (item, skip) => ({
+	item,
+	removeWorktree: false,
+	deleteBranch: false,
+	skip
+});
+/** What clean does with one item. */
+const cleanStep = (item, options) => {
+	if (item.inMainCheckout) return kept(item, MAIN_CHECKOUT);
+	if (item.heldBy !== void 0) return kept(item, `checked out in ${item.heldBy}`);
+	if (options.live?.has(item.runId) === true) return kept(item, RUN_GOING);
+	if (item.dirty && !options.force) return kept(item, "uncommitted changes");
+	if (item.branch === void 0 && item.checkedOut === void 0 && item.ahead > 0 && !options.force) return kept(item, "commits on no branch");
+	const removable = item.path !== null && !item.missing;
+	if (options.branches && item.branch !== void 0 && !item.merged && !options.force) return {
+		item,
+		removeWorktree: removable,
+		deleteBranch: false,
+		skip: "branch not merged"
+	};
+	return {
+		item,
+		removeWorktree: removable,
+		deleteBranch: options.branches && item.branch !== void 0
+	};
+};
+/** Whether a step drops a worktree whose folder is gone, by its own path. */
+const stepPrunes = (step) => step.item.missing && step.item.path !== null && step.skip === void 0;
+/** Whether a step does anything. */
+const stepActs = (step) => step.removeWorktree || step.deleteBranch || stepPrunes(step);
+/**
+* What `ork worktrees clean` would do. A worktree with uncommitted changes, an
+* unmerged branch, or a detached worktree holding commits no branch has, is
+* kept unless `force`; one checked out in the main checkout or in a worktree
+* Ork didn't create, or whose run is still going, is kept even then.
+*/
+const planClean = (items, filter, options) => items.filter((item) => filter.runId === void 0 || item.runId === filter.runId).filter((item) => filter.key === void 0 || keyOf(item) === filter.key).filter((item) => !filter.merged || item.merged).map((item) => cleanStep(item, options));
+/**
+* Carries out one step; what it did goes into `done` as it goes. It touches
+* only its own item: a missing worktree is dropped by its own path (`git
+* worktree remove`), never by `git worktree prune`, which would drop every
+* missing worktree in the repository, the user's own included.
+*/
+const applyStep = async (root, step, force, done) => {
+	const { item } = step;
+	if (stepPrunes(step) && !step.removeWorktree && item.path !== null) {
+		await gitOk(root, [
+			"worktree",
+			"remove",
+			item.path
+		]);
+		done.push(`pruned ${item.path}`);
+	}
+	if (step.removeWorktree && item.path !== null) {
+		await removeWorktree(root, item.path, force);
+		done.push(`removed ${item.path}`);
+	}
+	if (step.deleteBranch && item.branch !== void 0) {
+		await gitOk(root, [
+			"branch",
+			force ? "-D" : "-d",
+			item.branch
+		]);
+		done.push(`deleted ${item.branch}`);
+	}
+};
+/**
+* Carries out a clean plan, step by step. What it did goes into `done` as it
+* goes, so a caller still has it when git fails halfway.
+*/
+const applyClean = async (root, steps, force, done = []) => {
+	for (const step of steps) await applyStep(root, step, force, done);
+	return done;
+};
+export { planClean as a, keyOf as i, applyStep as n, stepActs as o, cleanStep as r, stepPrunes as s, applyClean as t };

package/dist/context-C_bksb0C.mjs

@@ -0,0 +1,351 @@
+import { _n as inside, _t as walkChecks, b as readProjectTriggers, dn as placeFiles, fn as placeFor, gn as workflowDirOf, gt as checkWorkflowText, mn as runDirOf, ot as explainSession, vt as walkSummary, x as workflowTextHash, yn as LESSON_CAP_TOKENS } from "./src-CGqMati3.mjs";
+import { b as builtinWorkflowFile, x as isBuiltinArg, y as builtinProblem } from "./__build_info__-CtSVVuZE.mjs";
+import { a as write, c as openStore, i as style, l as storePath, o as writeErr, r as plain } from "./output-CXSJO00X.mjs";
+import { defineCommand } from "citty";
+import path from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+// src/project/place.ts
+/**
+* @file Which project a folder belongs to, from the projects the store has
+*   registered (ADR-035): an attached project's files are in
+*   `~/.ork/projects/<id>/`, an in-repo one's in its `.ork/`.
+*/
+/** The registered projects; none before Ork has a store (never creates one). */
+const registeredProjects = (home) => {
+	const file = storePath(home);
+	if (!existsSync(file)) return [];
+	const store = openStore(file);
+	try {
+		return store.projects();
+	} finally {
+		store.close();
+	}
+};
+/** The project `dir` is in: registered, or the in-repo one at its git root. */
+const projectAt = (dir, home) => placeFor(dir, registeredProjects(home));
+/** A path to show: relative to `cwd` when inside it, else as it is. */
+const fromCwd = (target, cwd) => inside(cwd, target) ? path.relative(cwd, target) || "." : target;
+// src/workflows.ts
+/**
+* @file Finding workflow files: the project's workflows folder by default
+*   (`.ork/workflows/`, or an attached project's), directories expanded, a
+*   workflow given by name, and one of Ork's own by its `ork:` name, written
+*   into the project's run folder.
+*/
+const WORKFLOW_DIR = path.join(".ork", "workflows");
+const WORKFLOW_SUFFIX = ".ork.yaml";
+/**
+* Expands the given paths to workflow files: a directory contributes its
+* `*.ork.yaml` files, and a name one in the project's workflows folder
+* (`workflows`, default `.ork/workflows/` under `cwd`). With no paths, uses
+* that folder.
+*/
+const findWorkflowFiles = (paths, cwd, workflows = path.join(cwd, WORKFLOW_DIR)) => {
+	return (paths.length > 0 ? paths : [fromCwd(workflows, cwd)]).flatMap((target) => {
+		const absolute = path.resolve(cwd, target);
+		if (existsSync(absolute) && statSync(absolute).isDirectory()) return readdirSync(absolute).filter((name) => name.endsWith(WORKFLOW_SUFFIX)).toSorted().map((name) => path.join(target, name));
+		return [resolveWorkflowArg(target, cwd, workflows)];
+	});
+};
+/**
+* A workflow given by path, by name for one in the project's workflows folder
+* (`hello` is `.ork/workflows/hello.ork.yaml` when no file `hello` exists), or
+* by its `ork:` name for one of Ork's own. An unknown `ork:` name comes back as
+* it is: commands refuse it first (`unknownBuiltin`).
+*/
+const resolveWorkflowArg = (arg, cwd, workflows = path.join(cwd, WORKFLOW_DIR)) => {
+	if (isBuiltinArg(arg)) {
+		const file = builtinWorkflowFile(projectAt(cwd), arg);
+		return file === void 0 ? arg : fromCwd(file, cwd);
+	}
+	if (existsSync(path.resolve(cwd, arg)) || arg.endsWith(".ork.yaml")) return arg;
+	const named = path.join(workflows, `${arg}${WORKFLOW_SUFFIX}`);
+	return existsSync(named) ? fromCwd(named, cwd) : arg;
+};
+/**
+* Refuses an `ork:` name that isn't one of Ork's workflows, saying which are,
+* or whose file's place in the project is a link; true when it did, so the
+* command stops.
+*/
+const refusedBuiltin = (args, cwd) => {
+	const problems = args.filter((arg) => isBuiltinArg(arg)).flatMap((arg) => builtinProblem(projectAt(cwd), arg) ?? []);
+	for (const problem of problems) writeErr(problem);
+	if (problems.length > 0) process.exitCode = 1;
+	return problems.length > 0;
+};
+/**
+* A command's workflow argument, by path or by name in the project `cwd` is in,
+* with the project the file belongs to and a run's folder there.
+*/
+const workflowArg = (arg, cwd) => {
+	const file = resolveWorkflowArg(arg, cwd, placeFiles(projectAt(cwd)).workflows);
+	const place = projectAt(path.dirname(path.resolve(cwd, file)));
+	return {
+		file,
+		place,
+		runDir: (runId) => runDirOf(place, runId)
+	};
+};
+// src/commands/walk-report.ts
+/**
+* @file How `ork validate` shows a walk (RFC-009): one line on what it tried,
+*   and with `--paths`, each way a run can end. A gate's answer that ends the
+*   run shows here as an ending, not as a problem.
+*/
+const walkLine = (walk) => walk === void 0 ? [] : [style("dim", walkSummary(walk))];
+const endingLine = ({ status, notRun, paths }) => {
+	const ways = `${String(paths)} ${paths === 1 ? "way" : "ways"}`;
+	const word = status === "succeeded" ? style("green", status) : style("red", status);
+	const rest = notRun.length === 0 ? "every node ran" : `didn't run: ${notRun.map((id) => plain(id)).join(", ")}`;
+	return `  ${word} ${style("dim", `(${ways})`)} ${rest}`;
+};
+const endingLines = (ending) => [endingLine(ending), ...ending.choices.map((choice) => style("dim", `      ${plain(choice)}`))];
+/** Each ending, the ones that succeeded first, with one way to get there. */
+const pathLines = (walk) => {
+	const endings = walk?.endings ?? [];
+	return [...endings.filter(({ status }) => status === "succeeded"), ...endings.filter(({ status }) => status !== "succeeded")].flatMap((ending) => endingLines(ending));
+};
+// src/commands/validate.ts
+/**
+* @file `ork validate`: loads, parses and compiles workflow files with the
+*   project's rules (`.ork/project.yaml`) and the agents they name, checks
+*   their skill and context references, and reports diagnostics compiler-style,
+*   with file, line and column. `loadWorkflow` is shared with `ork run`.
+*/
+const hasErrors = (diagnostics) => diagnostics.some((d) => d.severity === "error");
+/**
+* Parses and compiles one workflow file, with the agents the user and its
+* project offer. `home` is the user's `~` (tests pass a folder); `registered`
+* the projects a caller's store has, else those of the store in `home`.
+*/
+const loadWorkflow = (file, cwd, home, registered = registeredProjects(home)) => {
+	const absolute = path.resolve(cwd, file);
+	const place = placeFor(path.dirname(absolute), registered);
+	const where = {
+		place,
+		workflowDir: workflowDirOf(place, absolute)
+	};
+	let text;
+	try {
+		text = readFileSync(path.resolve(cwd, file), "utf8");
+	} catch (error) {
+		return {
+			report: {
+				file,
+				diagnostics: [{
+					severity: "error",
+					code: "file.read",
+					message: error instanceof Error && "code" in error && error.code === "ENOENT" ? "file not found" : "cannot read file",
+					path: []
+				}]
+			},
+			workflow: null,
+			graph: null,
+			...where
+		};
+	}
+	const { diagnostics, workflow, graph, summary, locate } = checkWorkflowText(text, {
+		...where,
+		registered,
+		home
+	});
+	return {
+		report: {
+			file,
+			diagnostics,
+			...summary === void 0 ? {} : { summary }
+		},
+		workflow,
+		graph,
+		textHash: workflowTextHash(text),
+		...locate === void 0 ? {} : { locate },
+		...where
+	};
+};
+const validateFile = (file, cwd) => loadWorkflow(file, cwd).report;
+/**
+* Walks what loaded, with its findings on its report. `ork validate` and `ork
+* run` do this; the rest of what loads a workflow doesn't pay for a walk.
+*/
+const walkLoaded = async (loaded) => {
+	const { diagnostics, walk } = await walkChecks({
+		diagnostics: loaded.report.diagnostics,
+		graph: loaded.graph,
+		...loaded.locate === void 0 ? {} : { locate: loaded.locate }
+	});
+	return {
+		...loaded,
+		report: {
+			...loaded.report,
+			diagnostics,
+			...walk === void 0 ? {} : { walk }
+		}
+	};
+};
+const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+const diagnosticLine = (file, d) => {
+	const where = d.line === void 0 ? file : `${file}:${d.line}:${d.column ?? 1}`;
+	const severity = d.severity === "error" ? style(["red", "bold"], "error") : style(["yellow", "bold"], "warning");
+	return `${style("dim", where)} ${severity} ${d.message} ${style("dim", `(${d.code})`)}`;
+};
+/** The warnings alone, for a run that goes ahead despite them. */
+const warningLines = (report) => report.diagnostics.filter((d) => d.severity === "warning").map((d) => diagnosticLine(report.file, d));
+/** Human-readable report, one line per diagnostic, compiler style. */
+const formatReport = (report) => {
+	const lines = report.diagnostics.map((d) => diagnosticLine(report.file, d));
+	const errors = report.diagnostics.filter((d) => d.severity === "error").length;
+	const warnings = report.diagnostics.length - errors;
+	if (report.summary === void 0 && errors === 0) lines.push(`${style("green", "✓")} ${report.file}${warnings === 0 ? "" : style("dim", ` (${plural(warnings, "warning")})`)}`);
+	else if (report.summary !== void 0 && errors === 0) {
+		const { nodes, edges, entries } = report.summary;
+		const extra = warnings > 0 ? `, ${plural(warnings, "warning")}` : "";
+		lines.push(`${style("green", "✓")} ${report.file} ${style("dim", `(${plural(nodes, "node")}, ${plural(edges, "edge")}, starts at ${entries.join(", ")}${extra})`)}`);
+	} else lines.push(`${style("red", "✗")} ${report.file} ${style("dim", `(${plural(errors, "error")}, ${plural(warnings, "warning")})`)}`);
+	return [...lines, ...walkLine(report.walk)];
+};
+const validate = defineCommand({
+	meta: {
+		name: "validate",
+		description: "Check workflow files: schema, ownership tree, edges, loops and references, and walk every way through them"
+	},
+	args: {
+		json: {
+			type: "boolean",
+			description: "Print the reports as JSON",
+			default: false
+		},
+		paths: {
+			type: "boolean",
+			description: "List each way a run can end, and the choices that lead there",
+			default: false
+		}
+	},
+	run: async ({ args }) => {
+		const cwd = process.cwd();
+		if (refusedBuiltin(args._, cwd)) return;
+		const files = findWorkflowFiles(args._, cwd, placeFiles(projectAt(cwd)).workflows);
+		if (files.length === 0) {
+			write("No workflow files found. Run `ork init`, or pass a path.");
+			process.exitCode = 1;
+			return;
+		}
+		const place = projectAt(cwd);
+		const triggers = args._.length === 0 ? readProjectTriggers(place, void 0, registeredProjects()) : void 0;
+		const walked = [];
+		for (const file of files) {
+			const { report } = await walkLoaded(loadWorkflow(file, cwd));
+			walked.push(report);
+		}
+		const reports = [...walked, ...triggers?.present === true ? [{
+			file: path.relative(cwd, triggers.file),
+			diagnostics: [...triggers.diagnostics, ...triggers.triggers.flatMap((item) => item.diagnostics)]
+		}] : []];
+		if (args.json) write(JSON.stringify(reports, void 0, 2));
+		else for (const report of reports) {
+			for (const line of formatReport(report)) write(line);
+			if (args.paths) for (const line of pathLines(report.walk)) write(line);
+		}
+		if (reports.some((r) => hasErrors(r.diagnostics))) process.exitCode = 1;
+	}
+});
+// 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 { validate as a, warningLines as c, refusedBuiltin as d, workflowArg as f, loadWorkflow as i, WORKFLOW_DIR as l, registeredProjects as m, explainNode as n, validateFile as o, projectAt as p, formatReport as r, walkLoaded as s, context as t, WORKFLOW_SUFFIX as u };

package/dist/find-DptmbhGd.mjs

@@ -0,0 +1,47 @@
+import { fn as placeFor } from "./src-CGqMati3.mjs";
+import { randomUUID } from "node:crypto";
+// ../core/src/remote/find.ts
+/**
+* @file Finding a stored run from another process: by a run id or a unique
+*   prefix of one, or, with none, the newest run of the project a folder is in;
+*   and picking a new run's id. Shared by the CLI's commands and the local
+*   server (ADR-039).
+*/
+/** The run `arg` names, or the newest run of the project `cwd` is in. */
+const findRun = (store, arg, cwd) => {
+	if (arg === void 0 || arg === "") {
+		const [latest] = store.runs({
+			project: placeFor(cwd, store.projects()).root,
+			limit: 1
+		});
+		return latest === void 0 ? {
+			ok: false,
+			error: "No runs in this project yet; see `ork ps --all`."
+		} : {
+			ok: true,
+			run: latest
+		};
+	}
+	const found = store.lookup(arg);
+	const [only] = found;
+	if (only === void 0) return {
+		ok: false,
+		error: `No run \`${arg}\`.`
+	};
+	if (found.length > 1) return {
+		ok: false,
+		error: `\`${arg}\` matches ${String(found.length)} runs: ${found.map((r) => r.id).join(", ")}`
+	};
+	return {
+		ok: true,
+		run: only
+	};
+};
+/** A run id no stored run has yet; `node-…` for a run of one node. */
+const newRunId = (store, prefix = "") => {
+	for (;;) {
+		const id = `${prefix}${randomUUID().slice(0, 8)}`;
+		if (store.lookup(id).length === 0) return id;
+	}
+};
+export { newRunId as n, findRun as t };