omkit 0.4.8 → 0.8.1

package/dist/output/folder/RunFolder.js

@@ -1,7 +1,25 @@
 import { mkdirSync } from "node:fs";
 import path from "node:path";
-import { ymd, hms } from "../../foundation/format.js";
+import { ymd, hms, pad } from "../../foundation/format.js";
 import { fsSafe } from "../../foundation/fsSafe.js";
+import { newUuid, shortId } from "../../foundation/ids.js";
+/** Suffixed attempts (`-02` … `-99`) before falling back to a random, certainly-unique one. */
+const MAX_NUMBERED_ATTEMPTS = 99;
+/**
+ * Where `logs/` goes: the project root a frontend named, or the working directory when nobody
+ * named one.
+ *
+ * A run's cwd is not a statement about which project it belongs to — `omkit run` sets it to the
+ * om file's own directory so relative paths in a body resolve the way their author reads them,
+ * which meant one project scattered its records across every folder that happened to contain an
+ * om, while the MCP server wrote them wherever the server was started. Two names for one thing.
+ * The root is passed explicitly and separately so the record's location is a property of the
+ * project, and the cwd stays free to mean what it already meant.
+ */
+function logsRoot() {
+    const root = process.env.OMKIT_ROOT;
+    return root ? path.resolve(root, "logs") : path.resolve("logs");
+}
 /**
  * Owns this run's single output directory — `logs/<name>-<hash>/<date>/<time>/` —
  * where `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all
@@ -21,24 +39,65 @@ export class RunFolder {
     name() {
         return `${fsSafe(this.runName)}-${this.hash}`;
     }
-    /** The absolute run directory, computed once and created on first access. */
+    /**
+     * The absolute run directory — claimed on first access, stable thereafter.
+     *
+     * Claiming and knowing the path are the same act: the directory is what makes a run's
+     * identity exclusive, so there is no meaningful "what would the path be" to answer
+     * before it exists.
+     */
     path() {
-        if (this.dir)
-            return this.dir;
-        const now = new Date();
-        this.dir = path.resolve("logs", this.name(), ymd(now), hms(now, "-"));
+        if (!this.dir)
+            this.claim();
         return this.dir;
     }
     /** Absolute path to `name` inside the run folder; ensures the folder exists. */
     file(name) {
-        this.ensure();
         return path.join(this.path(), name);
     }
     /** Create the run folder synchronously (idempotent). */
     ensure() {
-        if (this.ensured)
-            return;
-        mkdirSync(this.path(), { recursive: true });
-        this.ensured = true;
+        this.path();
+    }
+    /**
+     * Take exclusive ownership of a `<date>/<time>` directory.
+     *
+     * `hms` has second resolution, so two runs of the same om starting within one second
+     * would otherwise share a folder — and that is not merely "the later one wins":
+     * `RawStream` opens `raw.jsonl` with `flags: "w"`, so two live runs both truncate it and
+     * then write at their own offsets, leaving bytes that are not valid JSONL. The MCP
+     * server makes this easy to reach, since `start_om` can put two children in flight.
+     *
+     * Finer timestamps would only lower the odds. `mkdirSync` without `recursive` throws
+     * `EEXIST` **atomically**, and that atomicity holds between processes — so the directory
+     * creation is itself the lock. The common case keeps a clean `16-39-29`; only a real
+     * collision produces `16-39-29-02`, zero-padded so lexical order stays chronological
+     * (which is what `latest` relies on).
+     */
+    claim() {
+        const now = new Date();
+        const parent = path.resolve(logsRoot(), this.name(), ymd(now));
+        mkdirSync(parent, { recursive: true });
+        const base = hms(now, "-");
+        for (let attempt = 0; attempt <= MAX_NUMBERED_ATTEMPTS; attempt += 1) {
+            // A random suffix as the last resort: bounded loops beat an unbounded one, and a
+            // hundred collisions inside one second means something stranger is going on.
+            const suffix = attempt === 0
+                ? ""
+                : attempt === MAX_NUMBERED_ATTEMPTS
+                    ? `-${shortId(newUuid())}`
+                    : `-${pad(attempt + 1)}`;
+            const candidate = path.join(parent, `${base}${suffix}`);
+            try {
+                mkdirSync(candidate); // deliberately not recursive — EEXIST is the lock
+                this.dir = candidate;
+                this.ensured = true;
+                return;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+            }
+        }
     }
 }

package/dist/output/writers/views.d.ts

@@ -21,6 +21,14 @@ export interface NodeView {
     readonly logFile: string;
     readonly children: readonly NodeView[];
 }
+/** A curated artifact, as projected into `result.json`. Data-only — no core import. */
+export interface ArtifactView {
+    readonly name: string;
+    /** Absolute path to the file. */
+    readonly file: string;
+    readonly description?: string;
+    readonly mime: string;
+}
 export interface RunView {
     readonly ok: boolean;
     readonly failures: ReadonlyArray<{
@@ -37,4 +45,6 @@ export interface RunView {
     /** Absolute path to `raw.jsonl`. */
     readonly rawStream: string;
     readonly root: NodeView;
+    /** Files the run labelled via `ctx.artifact`, in registration order. */
+    readonly artifacts: readonly ArtifactView[];
 }

package/dist/skill/file.d.ts

@@ -0,0 +1,26 @@
+/** Where the skill lands, relative to the project root that owns the tsconfig. */
+export declare const SKILL_RELATIVE_PATH: string;
+/**
+ * The `description` written into a file that does not exist yet.
+ *
+ * This field is the skill's loading trigger, so its wording decides whether an assistant reads
+ * the file at the right moment. A generated summary of contents ("lists 2 oms…") would be the
+ * wrong shape — the field has to say *when to use this*. So it is authored, and this is only
+ * the starting point: {@link readExisting} preserves whatever the author changes it to.
+ */
+export declare const DEFAULT_DESCRIPTION = "Runnable workflows in this repo (oms and actions) \u2014 what each does, its arguments, and how to run it. Load before running or debugging any project workflow.";
+/** What a previously generated file still has to say for itself. */
+export interface ExistingSkill {
+    /** The `description:` value, verbatim — continuation lines and all. */
+    readonly description?: string;
+    /** The `registry-hash` from the generated-by marker, when the file carries one. */
+    readonly hash?: string;
+}
+/**
+ * Read back the two things a regeneration must not lose: the authored description, and the
+ * hash to compare against. A missing or unreadable file is not an error — it is the "generate
+ * fresh" case, and returns an empty result.
+ */
+export declare function readExisting(file: string): ExistingSkill;
+/** Write the skill, creating its directory. The parent may not exist on a first generation. */
+export declare function writeSkill(file: string, content: string): void;

package/dist/skill/file.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+import { SKILL_NAME } from "./render.js";
+/** Where the skill lands, relative to the project root that owns the tsconfig. */
+export const SKILL_RELATIVE_PATH = path.join(".claude", "skills", SKILL_NAME, "SKILL.md");
+/**
+ * The `description` written into a file that does not exist yet.
+ *
+ * This field is the skill's loading trigger, so its wording decides whether an assistant reads
+ * the file at the right moment. A generated summary of contents ("lists 2 oms…") would be the
+ * wrong shape — the field has to say *when to use this*. So it is authored, and this is only
+ * the starting point: {@link readExisting} preserves whatever the author changes it to.
+ */
+export const DEFAULT_DESCRIPTION = "Runnable workflows in this repo (oms and actions) — what each does, its arguments, and how to run it. Load before running or debugging any project workflow.";
+/**
+ * Read back the two things a regeneration must not lose: the authored description, and the
+ * hash to compare against. A missing or unreadable file is not an error — it is the "generate
+ * fresh" case, and returns an empty result.
+ */
+export function readExisting(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return {};
+    }
+    const hash = /registry-hash:\s*([0-9a-f]{8})/.exec(text)?.[1];
+    const description = frontmatterDescription(text);
+    return { ...(description !== undefined ? { description } : {}), ...(hash ? { hash } : {}) };
+}
+/**
+ * Pull `description` out of the leading frontmatter, keeping any folded continuation lines
+ * exactly as written — they are re-emitted verbatim, so a wrapped description survives
+ * regeneration byte-for-byte instead of being reflowed into one long line.
+ */
+function frontmatterDescription(text) {
+    const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
+    if (block === undefined)
+        return undefined;
+    const lines = block.split(/\r?\n/);
+    const start = lines.findIndex((l) => l.startsWith("description:"));
+    if (start === -1)
+        return undefined;
+    const value = [lines[start].slice("description:".length).trimStart()];
+    // A continuation is any indented line; the next unindented line starts a new key.
+    for (const line of lines.slice(start + 1)) {
+        if (!/^\s+\S/.test(line))
+            break;
+        value.push(line);
+    }
+    return value.join("\n");
+}
+/** Write the skill, creating its directory. The parent may not exist on a first generation. */
+export function writeSkill(file, content) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content, "utf8");
+}

package/dist/skill/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The generated-skill layer: turn a project's registrations into `.claude/skills/omkit-runs/`.
+ *
+ * Split so that everything except {@link module:./file.ts} is pure — the model and the renderer
+ * take data and return data, which is what makes determinism testable without touching a disk.
+ */
+export { buildSkillModel, registryHash } from "./model.ts";
+export type { SkillCall, SkillEntry, SkillModel, SkillProject } from "./model.ts";
+export { skillRoot } from "./root.ts";
+export { renderSkill, generatedBy, SKILL_NAME } from "./render.ts";
+export { readExisting, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH } from "./file.ts";
+export type { ExistingSkill } from "./file.ts";

package/dist/skill/index.js

@@ -0,0 +1,10 @@
+/**
+ * The generated-skill layer: turn a project's registrations into `.claude/skills/omkit-runs/`.
+ *
+ * Split so that everything except {@link module:./file.ts} is pure — the model and the renderer
+ * take data and return data, which is what makes determinism testable without touching a disk.
+ */
+export { buildSkillModel, registryHash } from "./model.js";
+export { skillRoot } from "./root.js";
+export { renderSkill, generatedBy, SKILL_NAME } from "./render.js";
+export { readExisting, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH } from "./file.js";

package/dist/skill/model.d.ts

@@ -0,0 +1,69 @@
+import type { McpMode } from "../core/types.ts";
+import type { JsonSchema } from "../core/schema-json.ts";
+import type { OmCall, RegistrationSet, Registry } from "../client/registry.ts";
+/** One step in a rendered outline. Structurally an {@link OmCall}; named for the skill's vocabulary. */
+export type SkillCall = OmCall;
+/** One runnable thing the generated skill documents. */
+export interface SkillEntry {
+    readonly kind: "om" | "action";
+    readonly name: string;
+    /** Project-relative, forward slashes on every platform — so the file does not churn per-OS. */
+    readonly file: string;
+    readonly mode: McpMode;
+    /** The `.describe({ summary })` line. Absent when the author wrote none; never invented. */
+    readonly summary?: string;
+    /** A one-line sketch of the declared args, from {@link shapeHint}. */
+    readonly argHint?: string;
+    /** The raw schema, present only when `shapeHint` could not sketch it (per C7). */
+    readonly argSchema?: JsonSchema;
+    /** A concrete, complete `OMKIT_ARGS` value. Absent when no honest one can be built. */
+    readonly argExample?: Record<string, unknown>;
+    /** The static outline of the body. Absent when the walk found nothing recognisable. */
+    readonly calls?: readonly SkillCall[];
+    /** Why this entry cannot be called — carried through from discovery, rendered as a warning. */
+    readonly unavailable?: string;
+    /** Actions only: the exported binding a host om imports. */
+    readonly exportName?: string;
+    /** Actions only: true when the chain includes `.ref<…>()`, so it publishes a capability. */
+    readonly publishesCapability?: boolean;
+}
+/** The project the skill describes: where its reader stands, and what config omkit was given. */
+export interface SkillProject {
+    /** Directory the file is written for — `.claude/` lives here, and paths are relative to it. */
+    readonly root: string;
+    /** Absolute path of the tsconfig discovery ran against, when the caller knows it. */
+    readonly tsconfig?: string;
+}
+/** Everything the renderer needs, plus the hash that detects drift against it. */
+export interface SkillModel {
+    readonly oms: readonly SkillEntry[];
+    readonly actions: readonly SkillEntry[];
+    /**
+     * The `--tsconfig` value every rendered command needs, relative to the root. Absent when the
+     * CLI's own default already finds it — the flag would then be noise on every line.
+     */
+    readonly tsconfig?: string;
+    /** First 8 hex of sha256 over the registry data below — never over the rendered markdown. */
+    readonly hash: string;
+}
+/**
+ * Fold a project's registrations and its AST scan into the model the skill renders from.
+ *
+ * The two inputs answer different halves: the fork knows summaries, modes, and arg schemas
+ * (values that only exist once a module has been evaluated), while the AST scan knows the
+ * body outline and whether an action publishes a capability. Neither alone is enough.
+ *
+ * Only `.mcp()`-marked entries survive — exposure is opt-in, exactly as it is for the MCP
+ * server, so generating a skill can never widen what an assistant will attempt.
+ */
+export declare function buildSkillModel(registrations: RegistrationSet, registry: Registry, project: SkillProject): SkillModel;
+/**
+ * The staleness hash: first 8 hex of sha256 over the registry data, deliberately **not** over
+ * the rendered markdown, so reformatting the file does not read as drift.
+ *
+ * The outline is included even though the spec's list of inputs predates it: an edited om body
+ * changes what the file claims the run does, and leaving that undetected is exactly the silent
+ * drift the hash exists to catch. Keys are sorted before hashing so a schema serialised in a
+ * different property order cannot masquerade as a change.
+ */
+export declare function registryHash(entries: readonly SkillEntry[], tsconfig?: string): string;

package/dist/skill/model.js

@@ -0,0 +1,200 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { shapeHint } from "../core/schema-hint.js";
+import { DEFAULT_TSCONFIG } from "../client/types.js";
+/**
+ * Fold a project's registrations and its AST scan into the model the skill renders from.
+ *
+ * The two inputs answer different halves: the fork knows summaries, modes, and arg schemas
+ * (values that only exist once a module has been evaluated), while the AST scan knows the
+ * body outline and whether an action publishes a capability. Neither alone is enough.
+ *
+ * Only `.mcp()`-marked entries survive — exposure is opt-in, exactly as it is for the MCP
+ * server, so generating a skill can never widen what an assistant will attempt.
+ */
+export function buildSkillModel(registrations, registry, project) {
+    const { root } = project;
+    const outlines = new Map(registry.oms.map((o) => [key(o.name, o.file), o.calls]));
+    const capabilities = new Map(registry.actions.map((a) => [key(a.name, a.file), a.publishesCapability]));
+    const oms = registrations.oms
+        .filter(isExposed)
+        .map((om) => omEntry(om, outlines.get(key(om.name, om.file)), root))
+        .sort(byName);
+    const actions = registrations.actions
+        .filter(isExposed)
+        .map((a) => actionEntry(a, capabilities.get(key(a.name, a.file)), root))
+        .sort(byName);
+    const tsconfig = tsconfigFlag(project);
+    return {
+        oms,
+        actions,
+        ...(tsconfig ? { tsconfig } : {}),
+        hash: registryHash([...oms, ...actions], tsconfig),
+    };
+}
+/**
+ * What a reader standing at the root must pass as `--tsconfig`, or `undefined` when they need
+ * pass nothing. omkit looks for `tsconfig.omkit.json` in the working directory, so a project
+ * whose config sits anywhere else — the common case once an om project lives in a subfolder —
+ * has commands that only work with the flag. Rendering it is the difference between a file
+ * that documents how to run this project and one that documents how to run some other project.
+ */
+function tsconfigFlag({ root, tsconfig }) {
+    if (tsconfig === undefined)
+        return undefined;
+    const rel = relative(tsconfig, root);
+    return rel === DEFAULT_TSCONFIG ? undefined : rel;
+}
+function isExposed(r) {
+    return r.mcp !== undefined;
+}
+/** Identity for cross-referencing the two discovery passes: an om is its name in its file. */
+function key(name, file) {
+    return `${name}\0${path.resolve(file)}`;
+}
+/** Alphabetical by name, then by file — so two same-named oms in different files stay ordered. */
+function byName(a, b) {
+    return a.name.localeCompare(b.name) || a.file.localeCompare(b.file);
+}
+function omEntry(om, calls, root) {
+    return {
+        kind: "om",
+        name: om.name,
+        file: relative(om.file, root),
+        mode: om.mcp?.mode ?? "settling",
+        ...describeArgs(om.inputSchema),
+        ...(om.summary ? { summary: om.summary } : {}),
+        ...(calls?.length ? { calls } : {}),
+        ...(om.unavailable ? { unavailable: om.unavailable } : {}),
+    };
+}
+function actionEntry(action, publishesCapability, root) {
+    return {
+        kind: "action",
+        name: action.name,
+        file: relative(action.file, root),
+        mode: action.mcp?.mode ?? "settling",
+        exportName: action.exportName,
+        ...(publishesCapability ? { publishesCapability: true } : {}),
+        ...describeArgs(action.inputSchema),
+        ...(action.summary ? { summary: action.summary } : {}),
+        ...(action.unavailable ? { unavailable: action.unavailable } : {}),
+    };
+}
+function describeArgs(schema) {
+    if (!schema)
+        return {};
+    const hint = shapeHint(schema);
+    const example = argExample(schema);
+    return {
+        ...(hint === undefined ? { argSchema: schema } : { argHint: hint }),
+        ...(example ? { argExample: example } : {}),
+    };
+}
+/**
+ * A complete, valid `OMKIT_ARGS` object for this schema, or `undefined` when one cannot be
+ * built honestly.
+ *
+ * "Complete" is the whole point: an example missing a required field does not demonstrate the
+ * call, it demonstrates the prompt the reader gets instead. So every required field must be
+ * sampleable or there is no example — and when nothing is required, one optional field is
+ * enough to show the shape without implying the rest are needed.
+ */
+function argExample(schema) {
+    const properties = schema.properties;
+    if (typeof properties !== "object" || properties === null)
+        return undefined;
+    const entries = Object.entries(properties);
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const mandatory = entries.filter(([key]) => required.has(key));
+    if (mandatory.length > 0) {
+        const example = {};
+        for (const [key, field] of mandatory) {
+            const value = sample(field);
+            if (value === undefined)
+                return undefined;
+            example[key] = value;
+        }
+        return example;
+    }
+    for (const [key, field] of entries) {
+        const value = sample(field);
+        if (value !== undefined)
+            return { [key]: value };
+    }
+    return undefined;
+}
+/**
+ * One plausible value for a field, or `undefined` when the type has no short literal form.
+ * A declared default wins over an invented value — it is both valid and the author's own
+ * choice, which reads better in an example than a zero or an ellipsis.
+ */
+function sample(field) {
+    if (typeof field !== "object" || field === null)
+        return undefined;
+    const enumValues = field.enum;
+    if (Array.isArray(enumValues) && enumValues.length > 0)
+        return enumValues[0];
+    if (field.default !== undefined)
+        return field.default;
+    switch (field.type) {
+        case "string":
+            return "…";
+        case "number":
+        case "integer":
+            return 0;
+        case "boolean":
+            return false;
+        // Objects and arrays have no one-line stand-in: `{}` and `[]` are as likely to be rejected
+        // by the schema as accepted by it, and a rejected example is worse than none.
+        default:
+            return undefined;
+    }
+}
+/** Project-relative with forward slashes; absolute only if the file lies outside the root. */
+function relative(file, root) {
+    const rel = path.relative(root, file);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return posix(file);
+    return posix(rel);
+}
+const posix = (p) => p.split(path.sep).join("/").split("\\").join("/");
+/**
+ * The staleness hash: first 8 hex of sha256 over the registry data, deliberately **not** over
+ * the rendered markdown, so reformatting the file does not read as drift.
+ *
+ * The outline is included even though the spec's list of inputs predates it: an edited om body
+ * changes what the file claims the run does, and leaving that undetected is exactly the silent
+ * drift the hash exists to catch. Keys are sorted before hashing so a schema serialised in a
+ * different property order cannot masquerade as a change.
+ */
+export function registryHash(entries, tsconfig) {
+    const declarations = entries.map((e) => [
+        e.kind,
+        e.name,
+        e.file,
+        e.mode,
+        e.summary ?? "",
+        e.exportName ?? "",
+        e.unavailable ?? "",
+        e.publishesCapability === true,
+        e.argSchema ?? e.argHint ?? "",
+        (e.calls ?? []).map((c) => [c.name, c.tag ?? ""]),
+    ]);
+    // The invocation is hashed beside the declarations because it is part of what the file
+    // claims: move a project's tsconfig and every command in it becomes wrong, while not one
+    // om has changed. Drift is "the file no longer describes this project", not "an om changed".
+    const material = [declarations, tsconfig ?? ""];
+    return createHash("sha256").update(canonical(material)).digest("hex").slice(0, 8);
+}
+/** JSON with object keys sorted at every depth, so key order can never change the hash. */
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}

package/dist/skill/render.d.ts

@@ -0,0 +1,18 @@
+import type { SkillModel } from "./model.ts";
+/** The skill's directory name, and so the `name:` in its frontmatter. */
+export declare 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 declare const generatedBy: (hash: string) => string;
+/**
+ * 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 declare function renderSkill(model: SkillModel, opts: {
+    description: string;
+}): string;