@krapht/ork 0.1.0 → 0.3.0

package/dist/context-BFGC_C02.mjs

@@ -0,0 +1,435 @@
+import { E as planNodeSession, Qt as placeFor, Zt as placeFiles, an as practiceInstructions, ct as checkWorkflowText, en as runDirOf, g as workflowTextHash, h as readProjectTriggers, lt as walkChecks, nn as workflowDirOf, on as resolvePractices, rn as inside, ut as walkSummary } from "./src-Cz1yOUTg.mjs";
+import { a as write, c as openStore, i as style, l as storePath, r as plain } from "./output-Q2EdeVUt.mjs";
+import { defineCommand } from "citty";
+import path from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+// ../core/src/update/version.ts
+const VERSION = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u;
+/** `1.2.3`, `v1.2.3-beta.1` and the like; `null` for anything else. */
+const parseVersion = (text) => {
+	const match = VERSION.exec(text.trim());
+	if (match === null) return null;
+	const [, major = "0", minor = "0", patch = "0", pre] = match;
+	return {
+		core: [
+			Number(major),
+			Number(minor),
+			Number(patch)
+		],
+		pre: pre === void 0 ? [] : pre.split(".")
+	};
+};
+const NUMERIC = /^\d+$/u;
+/** One pre-release identifier against another: numbers sort below words. */
+const compareIdentifier = (a, b) => {
+	const an = NUMERIC.test(a);
+	const bn = NUMERIC.test(b);
+	if (an && bn) return Number(a) - Number(b);
+	if (an !== bn) return an ? -1 : 1;
+	return a < b ? -1 : Number(a > b);
+};
+const comparePre = (a, b) => {
+	if (a.length === 0 || b.length === 0) return b.length - a.length;
+	for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+		const order = compareIdentifier(a[i] ?? "", b[i] ?? "");
+		if (order !== 0) return order;
+	}
+	return a.length - b.length;
+};
+/** Semver precedence: negative when `a` is older, 0 when equal. */
+const compareVersions = (a, b) => {
+	for (let i = 0; i < 3; i += 1) {
+		const order = (a.core[i] ?? 0) - (b.core[i] ?? 0);
+		if (order !== 0) return order;
+	}
+	return comparePre(a.pre, b.pre);
+};
+/** Whether `candidate` is newer than `current`; false when either is invalid. */
+const isNewer = (candidate, current) => {
+	const a = parseVersion(candidate);
+	const b = parseVersion(current);
+	return a !== null && b !== null && compareVersions(a, b) > 0;
+};
+// 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, and a
+*   workflow given by name.
+*/
+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, or by name for one in the project's workflows
+* folder: `hello` is `.ork/workflows/hello.ork.yaml` when no file `hello`
+* exists.
+*/
+const resolveWorkflowArg = (arg, cwd, workflows = path.join(cwd, WORKFLOW_DIR)) => {
+	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;
+};
+/**
+* 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();
+		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. 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. Plans the session without
+*   writing anything.
+*/
+/** A rough count, for comparing sizes: about four characters a token. */
+const tokens = (text) => Math.ceil(text.length / 4);
+/** Which project instruction file Claude Code reads from the checkout. */
+const instructionsOf = (stack, checkout) => {
+	if (stack.instructions === "ignore") return "left out (project.instructions: ignore)";
+	const has = (file) => existsSync(path.join(checkout, file));
+	if ([
+		"CLAUDE.md",
+		".claude/CLAUDE.md",
+		"CLAUDE.local.md"
+	].some((file) => has(file))) return "CLAUDE.md, loaded by Claude Code";
+	if (has("AGENTS.md")) return "AGENTS.md, loaded by Claude Code";
+	return "none in the project";
+};
+const skillLines = (stack, root) => stack.skills.map((skill) => {
+	const source = skill.text === void 0 ? path.relative(root, skill.dir) || "." : "built-in";
+	const line = {
+		name: skill.layer !== "project" ? `ork:${skill.name}` : skill.name,
+		layer: skill.layer,
+		source: source.startsWith("..") ? skill.dir : source,
+		state: skill.shadowedBy === void 0 && skill.ignored === void 0 ? "live" : "off",
+		tokens: tokens(skill.text ?? readFileSync(path.join(skill.dir, "SKILL.md"), "utf8"))
+	};
+	if (skill.shadowedBy !== void 0) line.why = `shadowed by the ${skill.shadowedBy} layer`;
+	else if (skill.ignored !== void 0) line.why = skill.ignored === "ignore" ? "project.skills: ignore" : "not in project.skills.allow";
+	return line;
+});
+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 { root } = place;
+	const plan = planNodeSession(workflow, nodeId, {
+		cwd: root,
+		inputs: {},
+		inPlace: true,
+		workflowDir,
+		projectRoot: root,
+		orkDir: place.dir,
+		...home === void 0 ? {} : { home }
+	});
+	if (!plan.ok) return {
+		ok: false,
+		lines: [plan.error]
+	};
+	const { context } = plan;
+	const practices = practiceInstructions(resolvePractices(workflow, nodeId), root);
+	const names = ["caveman", "ponytail"].filter((n) => !practices.skipped.includes(n));
+	const ref = graph?.agents.get(nodeId);
+	const role = ref === void 0 ? void 0 : workflow.agents?.[ref.name]?.instructions;
+	return {
+		ok: true,
+		explanation: {
+			node: nodeId,
+			type: workflow.nodes[nodeId]?.type ?? "",
+			workflow: workflow.name,
+			...ref === void 0 ? {} : { agent: {
+				name: ref.name,
+				where: ref.where,
+				tokens: tokens(role ?? "")
+			} },
+			instructions: instructionsOf(context, root),
+			skills: skillLines(context, root),
+			files: context.files.map((f) => ({
+				layer: f.layer,
+				name: f.name,
+				tokens: tokens(f.text)
+			})),
+			practices: practices.text.map((text, index) => ({
+				name: names[index] ?? "practice",
+				tokens: tokens(text)
+			})),
+			skippedPractices: practices.skipped,
+			appendedTokens: tokens(plan.spec.systemAppend)
+		}
+	};
+};
+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.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) lines.push(`  ${f.layer.padEnd(8)}  ${f.name}  ${approx(f.tokens)}`);
+	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, or the name of one in the project's workflows (.ork/workflows/)",
+			required: true
+		},
+		node: {
+			type: "positional",
+			description: "Node id",
+			required: true
+		},
+		json: {
+			type: "boolean",
+			description: "Print JSON",
+			default: false
+		}
+	},
+	run: ({ args }) => {
+		const cwd = process.cwd();
+		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, workflowArg as d, projectAt as f, loadWorkflow as i, WORKFLOW_DIR as l, explainNode as n, validateFile as o, isNewer as p, formatReport as r, walkLoaded as s, context as t, WORKFLOW_SUFFIX as u };

package/dist/find-BcvhT6UN.mjs

@@ -0,0 +1,47 @@
+import { Qt as placeFor } from "./src-Cz1yOUTg.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 };