omkit 0.4.8 → 0.8.1

package/dist/skill/render.js

@@ -0,0 +1,159 @@
+/** The skill's directory name, and so the `name:` in its frontmatter. */
+export const SKILL_NAME = "omkit-runs";
+/**
+ * The marker line that carries the staleness hash. Written by {@link renderSkill} and read
+ * back by the file layer, so the two agree on one format rather than two regexes.
+ */
+export const generatedBy = (hash) => `<!-- GENERATED by \`omkit skill\`. Do not edit. registry-hash: ${hash} -->`;
+/**
+ * Render the model as the skill's markdown.
+ *
+ * Deterministic by construction: no timestamps, no absolute paths, no iteration over unordered
+ * collections — the model arrives sorted. A generated file that is committed and churns on
+ * every run is a file people stop reading.
+ */
+export function renderSkill(model, opts) {
+    const lines = [
+        "---",
+        `name: ${SKILL_NAME}`,
+        `description: ${opts.description}`,
+        "---",
+        "",
+        "# omkit — runnable workflows",
+        "",
+        generatedBy(model.hash),
+        "",
+        ...howToRun(model),
+        ...workflows(model),
+        ...actions(model),
+        ...whereOutputLands(model),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function howToRun(model) {
+    // A long-lived om is the wrong thing to demonstrate `run` with: it never returns, and the
+    // entry's own heading says so a few lines further down. Prefer one that settles, and fall
+    // back to the long-lived one only when the project has nothing else — annotated, so the
+    // command still reads as deliberate rather than as an example that hangs.
+    const settling = model.oms.filter((o) => o.mode !== "long-lived");
+    const pool = settling.length ? settling : model.oms;
+    const example = pool[0];
+    const withArgs = pool.find((o) => o.argExample !== undefined);
+    const name = example?.name ?? "<om>";
+    const holds = example?.mode === "long-lived" ? "  # long-lived: runs until you stop it" : "";
+    // Appended to every command, because omkit resolves its config against the working directory
+    // and this file's reader is at the project root, which is not necessarily where the config is.
+    const config = model.tsconfig ? ` --tsconfig ${model.tsconfig}` : "";
+    return [
+        "## How to run",
+        "",
+        "**Shell — always available.** Run these from the project root (the directory holding",
+        "`.claude/`); every path here is relative to it.",
+        "",
+        "```bash",
+        `npx omkit run ${shellName(name)}${config}${holds}`,
+        // Only when there is a real one to show. An `OMKIT_ARGS='{}'` line teaches the syntax and
+        // nothing else, and reads as though this project's runs take no arguments — which is the
+        // opposite of what it means when a project's args could not be sampled.
+        ...(withArgs
+            ? [
+                `OMKIT_ARGS='${JSON.stringify(withArgs.argExample)}' npx omkit run ${shellName(withArgs.name)}${config}`,
+            ]
+            : []),
+        "```",
+        "",
+        "Arguments travel as one JSON object in `OMKIT_ARGS`. Anything an om declares but does not",
+        "receive is filled from the schema's defaults, and only then by asking.",
+        "",
+        '**MCP — if configured:** `run_om("<name>", { …args })` runs a settling workflow to',
+        "completion and returns its verdict; `start_om` starts a long-lived one and returns a run id",
+        "to poll with `get_run`, read with `tail_run`, and end with `cancel_run`.",
+        "",
+        `To wire it up: \`claude mcp add omkit -- npx omkit mcp${config}\``,
+        "",
+        "At runtime `list_oms` is authoritative — this file is orientation, and can drift.",
+        "",
+    ];
+}
+/**
+ * An om's name as one shell argument.
+ *
+ * A name is free text — `om("DTF Tests")` is legal, and reads well in a log — but written bare
+ * into a command it stops being one argument: `omkit run DTF Tests` resolves the target as
+ * "DTF" and leaves "Tests" as a stray positional. So the file carries the quotes rather than
+ * leaving the reader to notice they are missing.
+ *
+ * Double quotes, not single, because cmd.exe and PowerShell understand them too. Names built
+ * from shell metacharacters beyond a quote or a backslash (`$`, backticks) are the author's to
+ * avoid — there is no quoting form that is literal in every shell at once.
+ */
+const shellName = (name) => /^[\w:.@/-]+$/.test(name) ? name : `"${name.replace(/([\\"])/g, "\\$1")}"`;
+function workflows(model) {
+    if (model.oms.length === 0) {
+        return ["## Workflows", "", "_None exposed. Mark an om with `.mcp()` to list it here._", ""];
+    }
+    return ["## Workflows", "", ...model.oms.flatMap((om) => entry(om, omHeading(om)))];
+}
+function actions(model) {
+    if (model.actions.length === 0)
+        return [];
+    return [
+        "## Actions",
+        "",
+        "An action is a step, not a run. It cannot execute on its own — omkit hosts it in a",
+        "generated om so it has a run to belong to, which means it gets its own run folder and",
+        "verdict like anything else.",
+        "",
+        ...model.actions.flatMap((a) => entry(a, `### \`${a.name}\``)),
+    ];
+}
+function omHeading(om) {
+    const mode = om.mode === "long-lived" ? "long-lived · `start_om` only, it does not finish" : "settling";
+    return `### \`${om.name}\` — ${mode}`;
+}
+function entry(e, heading) {
+    const lines = [heading, ""];
+    lines.push(e.summary ?? "_No summary. The author can add one with `.describe({ summary })`._", "");
+    lines.push(`- **Defined in:** \`${e.file}\``);
+    if (e.kind === "action" && e.exportName)
+        lines.push(`- **Exported as:** \`${e.exportName}\``);
+    if (e.argHint)
+        lines.push(`- **Args:** \`${e.argHint}\``);
+    if (e.calls?.length)
+        lines.push(`- **Calls:** ${e.calls.map(renderCall).join(" → ")}`);
+    if (e.publishesCapability) {
+        lines.push("- **Publishes a capability.** It hands a live handle to whatever runs after it. Run on", "  its own there is no downstream, so the handle goes nowhere — useful for a smoke test,", "  not for the thing the capability was for.");
+    }
+    if (e.unavailable)
+        lines.push(`- **Not callable:** ${e.unavailable}`);
+    if (e.argSchema) {
+        lines.push("- **Args** (no short form — the schema is the contract):", "", "```json");
+        lines.push(JSON.stringify(e.argSchema, null, 2));
+        lines.push("```");
+    }
+    lines.push("");
+    return lines;
+}
+/** The model's paths are already posix, so the directory half is a plain string operation. */
+const posixDirname = (file) => file.slice(0, Math.max(0, file.lastIndexOf("/")));
+const renderCall = (c) => c.tag ? `\`${c.name}\` [${c.tag}]` : `\`${c.name}\``;
+function whereOutputLands(model) {
+    // Spelled from the root the reader stands at, not as a bare `logs/`: the folder belongs to
+    // the project that owns the config, which in a subfolder layout is not where they are.
+    const dir = model.tsconfig ? posixDirname(model.tsconfig) : "";
+    const logs = dir ? `${dir}/logs` : "logs";
+    return [
+        "## Where output lands",
+        "",
+        `\`${logs}/<name>-<hash8>/<date>/<time>/\` — \`main.log\`, \`result.json\`, \`artifacts.log\`,`,
+        "`events.log`, `asserts.log`, `raw.jsonl`. A run's identity is its name plus its defining",
+        'file, so "the latest run of X" is always resolvable without parsing scrollback.',
+        "",
+        "## What the outlines above do and do not tell you",
+        "",
+        "**Calls** is a static reading of the body, not a trace. A conditional call is listed",
+        "unconditionally, a loop is listed once, an action chosen at runtime is not listed at all,",
+        'and a call made inside a helper function is invisible to it. Read it as "roughly what',
+        'happens in here" and read `result.json` for what actually did.',
+    ];
+}

package/dist/skill/root.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The directory a generated skill is written for: the nearest enclosing repository, or the
+ * project itself when there is none.
+ *
+ * The root is not really a free choice. A skill file lives at `.claude/skills/<name>/SKILL.md`,
+ * an assistant reads it with the repository as its working directory, and so every path and
+ * command inside has to be relative to *that* — not to wherever the om project's tsconfig
+ * happens to sit. Defaulting to the tsconfig's own directory made the common monorepo layout
+ * (an `om/` folder beside the code it drives) wrong by default, and needed a second flag to
+ * correct what the first flag had just decided.
+ *
+ * `.git` is checked as an entry, not as a directory: a worktree or submodule records it as a
+ * file containing a `gitdir:` pointer, and that is still the top of the checkout.
+ */
+export declare function skillRoot(projectDir: string): string;

package/dist/skill/root.js

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * The directory a generated skill is written for: the nearest enclosing repository, or the
+ * project itself when there is none.
+ *
+ * The root is not really a free choice. A skill file lives at `.claude/skills/<name>/SKILL.md`,
+ * an assistant reads it with the repository as its working directory, and so every path and
+ * command inside has to be relative to *that* — not to wherever the om project's tsconfig
+ * happens to sit. Defaulting to the tsconfig's own directory made the common monorepo layout
+ * (an `om/` folder beside the code it drives) wrong by default, and needed a second flag to
+ * correct what the first flag had just decided.
+ *
+ * `.git` is checked as an entry, not as a directory: a worktree or submodule records it as a
+ * file containing a `gitdir:` pointer, and that is still the top of the checkout.
+ */
+export function skillRoot(projectDir) {
+    let dir = path.resolve(projectDir);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, ".git")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return path.resolve(projectDir);
+        dir = parent;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.4.8",
+  "version": "0.8.1",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -52,11 +53,13 @@
     "developer-tools"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "ink": "^7.1.1",
     "patch-console": "^2.0.0",
     "playwright-core": "^1.49.0",
     "react": "^19.2.8",
     "tsx": "4.23.1",
+    "zod": "^4.4.3",
     "zx": "^8.8.5"
   },
   "devDependencies": {