@netnodeag/kraftwerk 0.79.0 → 0.80.0

package/dist/core/refs.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The reference registry: everything in a workspace that can be pointed
+ * at by name — knowledge bundles, vibeables, repositories, workflows,
+ * agents, projects, contacts, places and events. Each kind registers only
+ * a lookup (its storage and routes stay where they are); one resolver then
+ * serves every place a reference appears: a project's link lists, an
+ * event's place and contacts, a `contact:anna-meier` token in text, the
+ * ⌘K palette and the context an agent starts with.
+ *
+ * A reference is `<token>:<slug>` — the kind's singular token (contact,
+ * place, event, project, agent, workflow, repo, vibeable, knowledge) and
+ * the target's slug. Only registered tokens match, so `https:` and the
+ * like never do. A target that does not exist is reported (found: false),
+ * never an error — the same rule project links have always followed.
+ */
+export declare const REF_KIND_NAMES: readonly ["knowledge", "vibeables", "repos", "workflows", "agents", "projects", "contacts", "places", "events"];
+/** The kind's plural: the link-list name in project.yml and the folder/route name. */
+export type RefKind = (typeof REF_KIND_NAMES)[number];
+/** One existing target. */
+export interface RefTarget {
+    slug: string;
+    /** Display text next to the slug (an agent's name, a bundle's size); "" when there is nothing to add. */
+    label: string;
+    /** Where the web UI opens it (a hash route). */
+    href: string;
+}
+export interface RefKindDef {
+    kind: RefKind;
+    /** The token in text: contact in contact:anna-meier. */
+    token: string;
+    /** How the kind reads in a sentence ("knowledge bundle", "contact"). */
+    noun: string;
+    /** Every target that exists right now; [] when the feature is off. */
+    list(): Promise<RefTarget[]>;
+}
+/** One referenced slug and whether its target exists right now. */
+export interface LinkState {
+    slug: string;
+    found: boolean;
+    /** Display name of the target when found (an agent's name, a workflow's description). */
+    label?: string;
+}
+/** A `kind:slug` token, resolved. */
+export interface ResolvedRef extends LinkState {
+    kind: RefKind;
+    token: string;
+    href: string;
+}
+export declare const REF_KINDS: readonly RefKindDef[];
+/** The kind registered under a plural name or a token; undefined for anything else. */
+export declare const refKind: (name: string) => RefKindDef | undefined;
+/** Which of the slugs exist right now, per kind. Kinds without slugs are not listed at all. */
+export declare function resolveRefs<K extends RefKind>(byKind: Record<K, string[]>): Promise<Record<K, LinkState[]>>;
+/** A `token:slug` reference in text: a registered token, a colon, a slug — not inside a word, a path or a URL. */
+export declare const REF_TOKEN_RE: RegExp;
+/** Every distinct reference in a text, in order of appearance. */
+export declare function findRefs(text: string): Array<{
+    token: string;
+    kind: RefKind;
+    slug: string;
+}>;
+/** Parse one reference ("contact:anna-meier"); null when it is not one. */
+export declare function parseRef(text: string): {
+    token: string;
+    kind: RefKind;
+    slug: string;
+} | null;
+/** Resolve references: each with whether its target exists and where it opens. */
+export declare function resolveTokens(refs: Array<{
+    kind: RefKind;
+    slug: string;
+}>): Promise<ResolvedRef[]>;
+/** Resolve one reference written as text; null when the text is not a reference. */
+export declare function resolveRef(text: string): Promise<ResolvedRef | null>;

package/dist/core/refs.js

@@ -0,0 +1,143 @@
+import { listAgents } from "./agents.js";
+import { CONTACTS, EVENTS, listEntities, PLACES } from "./entities.js";
+import { knowledgeIndex } from "./knowledge.js";
+import { listProjects } from "./projects.js";
+import { listRepos } from "./repos.js";
+import { listVibeables } from "./vibeables.js";
+import { listWorkflows } from "./workflows.js";
+/**
+ * The reference registry: everything in a workspace that can be pointed
+ * at by name — knowledge bundles, vibeables, repositories, workflows,
+ * agents, projects, contacts, places and events. Each kind registers only
+ * a lookup (its storage and routes stay where they are); one resolver then
+ * serves every place a reference appears: a project's link lists, an
+ * event's place and contacts, a `contact:anna-meier` token in text, the
+ * ⌘K palette and the context an agent starts with.
+ *
+ * A reference is `<token>:<slug>` — the kind's singular token (contact,
+ * place, event, project, agent, workflow, repo, vibeable, knowledge) and
+ * the target's slug. Only registered tokens match, so `https:` and the
+ * like never do. A target that does not exist is reported (found: false),
+ * never an error — the same rule project links have always followed.
+ */
+export const REF_KIND_NAMES = ["knowledge", "vibeables", "repos", "workflows", "agents", "projects", "contacts", "places", "events"];
+/** A list that fails to read is an empty list: a reference into it is "not found", never an error. */
+const safe = async (p, fallback) => p.catch(() => fallback);
+export const REF_KINDS = [
+    {
+        kind: "knowledge",
+        token: "knowledge",
+        noun: "knowledge bundle",
+        list: async () => (await safe(knowledgeIndex(), { bundles: [] })).bundles.map((b) => ({ slug: b.name, label: `${b.concepts} concepts`, href: `/knowledge/${b.name}` })),
+    },
+    {
+        kind: "vibeables",
+        token: "vibeable",
+        noun: "vibeable",
+        list: async () => (await safe(listVibeables(), { vibeables: [] })).vibeables.map((v) => ({ slug: v.slug, label: v.dev ? "dev" : "static", href: `/vibeables/${v.slug}` })),
+    },
+    {
+        kind: "repos",
+        token: "repo",
+        noun: "repository",
+        list: async () => (await safe(listRepos(), { repos: [] })).repos.map((r) => ({ slug: r.slug, label: r.branch ?? "", href: `/repos/${r.slug}` })),
+    },
+    {
+        kind: "workflows",
+        token: "workflow",
+        noun: "workflow",
+        list: async () => (await safe(listWorkflows(), { workflows: [] })).workflows.map((w) => ({ slug: w.slug, label: w.description ?? w.name ?? "", href: `/workflows/${w.slug}` })),
+    },
+    {
+        kind: "agents",
+        token: "agent",
+        noun: "agent",
+        list: async () => (await safe(listAgents(), []))
+            .filter((a) => !a.archived)
+            .map((a) => ({ slug: a.slug, label: `${a.emoji} ${a.name}`, href: `/agents/${a.slug}` })),
+    },
+    {
+        kind: "projects",
+        token: "project",
+        noun: "project",
+        list: async () => (await safe(listProjects(), { projects: [] })).projects.map((p) => ({ slug: p.slug, label: p.title, href: `/projects/${p.slug}` })),
+    },
+    {
+        kind: "contacts",
+        token: "contact",
+        noun: "contact",
+        list: async () => (await safe(listEntities(CONTACTS), { items: [] })).items.map((c) => ({ slug: c.slug, label: CONTACTS.describe(c), href: `/contacts/${c.slug}` })),
+    },
+    {
+        kind: "places",
+        token: "place",
+        noun: "place",
+        list: async () => (await safe(listEntities(PLACES), { items: [] })).items.map((p) => ({ slug: p.slug, label: PLACES.describe(p), href: `/places/${p.slug}` })),
+    },
+    {
+        kind: "events",
+        token: "event",
+        noun: "event",
+        list: async () => (await safe(listEntities(EVENTS), { items: [] })).items.map((e) => ({ slug: e.slug, label: EVENTS.describe(e), href: `/events/${e.slug}` })),
+    },
+];
+const byKind = new Map(REF_KINDS.map((d) => [d.kind, d]));
+const byToken = new Map(REF_KINDS.map((d) => [d.token, d]));
+/** The kind registered under a plural name or a token; undefined for anything else. */
+export const refKind = (name) => byKind.get(name) ?? byToken.get(name);
+/** The link states of some slugs against one list of targets. */
+const states = (slugs, targets) => slugs.map((slug) => {
+    const t = targets.find((x) => x.slug === slug);
+    return t ? { slug, found: true, ...(t.label ? { label: t.label } : {}) } : { slug, found: false };
+});
+/** Which of the slugs exist right now, per kind. Kinds without slugs are not listed at all. */
+export async function resolveRefs(byKind) {
+    const out = {};
+    await Promise.all(Object.keys(byKind).map(async (kind) => {
+        const slugs = byKind[kind];
+        const def = refKind(kind);
+        out[kind] = !def || slugs.length === 0 ? [] : states(slugs, await def.list());
+    }));
+    return out;
+}
+const SLUG = "[a-z0-9][a-z0-9-]{0,48}";
+/** A `token:slug` reference in text: a registered token, a colon, a slug — not inside a word, a path or a URL. */
+export const REF_TOKEN_RE = new RegExp(`(?<![\\w/:.@-])(${REF_KINDS.map((d) => d.token).join("|")}):(${SLUG})(?![\\w-])`, "g");
+/** Every distinct reference in a text, in order of appearance. */
+export function findRefs(text) {
+    const seen = new Set();
+    const out = [];
+    for (const m of text.matchAll(REF_TOKEN_RE)) {
+        const token = m[0];
+        if (seen.has(token))
+            continue;
+        seen.add(token);
+        out.push({ token, kind: byToken.get(m[1]).kind, slug: m[2] });
+    }
+    return out;
+}
+/** Parse one reference ("contact:anna-meier"); null when it is not one. */
+export function parseRef(text) {
+    const m = new RegExp(`^(${REF_KINDS.map((d) => d.token).join("|")}|${REF_KIND_NAMES.join("|")}):(${SLUG})$`).exec(text.trim());
+    if (!m)
+        return null;
+    const def = refKind(m[1]);
+    return { token: `${def.token}:${m[2]}`, kind: def.kind, slug: m[2] };
+}
+/** Resolve references: each with whether its target exists and where it opens. */
+export async function resolveTokens(refs) {
+    const kinds = [...new Set(refs.map((r) => r.kind))];
+    const lists = new Map(await Promise.all(kinds.map(async (k) => [k, await refKind(k).list()])));
+    return refs.map((r) => {
+        const def = refKind(r.kind);
+        const t = lists.get(r.kind).find((x) => x.slug === r.slug);
+        return { kind: r.kind, token: `${def.token}:${r.slug}`, slug: r.slug, found: !!t, ...(t?.label ? { label: t.label } : {}), href: t?.href ?? `/${r.kind}/${r.slug}` };
+    });
+}
+/** Resolve one reference written as text; null when the text is not a reference. */
+export async function resolveRef(text) {
+    const ref = parseRef(text);
+    if (!ref)
+        return null;
+    return (await resolveTokens([ref]))[0];
+}

package/dist/core/search.d.ts

@@ -25,6 +25,16 @@ export interface WorkspaceAgents {
     channels: ChannelSummary[];
     /** Projects that are not archived; empty when the feature is off. */
     projects: ProjectHit[];
+    /** Contacts, places and events of this instance (the registry does not carry them); empty for other workspaces and while the features are off. */
+    entities: EntityHit[];
+}
+/** What the palette needs of a contact, place or event. */
+export interface EntityHit {
+    kind: "contacts" | "places" | "events";
+    slug: string;
+    title: string;
+    /** The rest of its one-line description (role and org, address, date). */
+    detail?: string;
 }
 export interface AgentSearch {
     workspaces: WorkspaceAgents[];

package/dist/core/search.js

@@ -4,7 +4,17 @@ import { workspaceRoot } from "./context.js";
 import { listAgents, toSummary } from "./agents.js";
 import { listChannels, toChannelSummary } from "./channels.js";
 import { currentInstanceUrl, discoverWorkspaces, listWorkspaceRecords } from "./instances.js";
+import { CONTACTS, EVENTS, listEntities, PLACES } from "./entities.js";
 import { listProjects, toProjectHit } from "./projects.js";
+async function entityHits(def) {
+    const view = await listEntities(def).catch(() => ({ items: [] }));
+    return view.items
+        .filter((e) => !e.configError)
+        .map((e) => {
+        const detail = def.detail(e);
+        return { kind: def.kind, slug: e.slug, title: e.title, ...(detail ? { detail } : {}) };
+    });
+}
 export async function searchAgents() {
     const project = await resolveWorkspace(workspaceRoot()).catch(() => null);
     const self = {
@@ -17,6 +27,7 @@ export async function searchAgents() {
         agents: (await listAgents().catch(() => [])).filter((a) => !a.archived).map(toSummary),
         channels: (await listChannels().catch(() => [])).map(toChannelSummary),
         projects: (await listProjects().catch(() => ({ projects: [] }))).projects.filter((p) => p.status !== "archived").map(toProjectHit),
+        entities: (await Promise.all([CONTACTS, PLACES, EVENTS].map(entityHits))).flat(),
     };
     const [workspaces, known] = await Promise.all([discoverWorkspaces(), listWorkspaceRecords()]);
     const records = new Map(known.map((p) => [p.root, p]));
@@ -33,6 +44,7 @@ export async function searchAgents() {
         agents: records.get(w.root)?.agents ?? [],
         channels: records.get(w.root)?.channels ?? [],
         projects: records.get(w.root)?.projects ?? [],
+        entities: [],
     }));
     return { workspaces: [self, ...others] };
 }

package/dist/core/settings.d.ts

@@ -32,6 +32,10 @@ export interface SaveSettingsInput {
     vibeables?: ReposSettingsInput;
     /** Omitted = untouched. Same shape and rules as repos. */
     projects?: ReposSettingsInput;
+    /** Omitted = untouched. Same shape and rules as repos. */
+    contacts?: ReposSettingsInput;
+    places?: ReposSettingsInput;
+    events?: ReposSettingsInput;
 }
 export interface ReposSettingsInput {
     enabled: boolean;

package/dist/core/settings.js

@@ -1,7 +1,8 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "yaml";
-import { ignoreEntryFor, PROJECTS_DEFAULT_ROOT, REPOS_DEFAULT_ROOT, resolveWorkspace, VIBEABLES_DEFAULT_ROOT, isSafeGitName } from "../config.js";
+import { ENTITY_KINDS, entityDefaultRoot, ignoreEntryFor, PROJECTS_DEFAULT_ROOT, REPOS_DEFAULT_ROOT, resolveWorkspace, VIBEABLES_DEFAULT_ROOT, isSafeGitName } from "../config.js";
+import { ensureEntitiesRoot } from "./entities.js";
 import { ensureProjectsRoot } from "./projects.js";
 import { disposeAllDevs, ensureVibeablesRoot } from "./vibeables.js";
 import { workspaceRoot } from "./context.js";
@@ -76,8 +77,15 @@ function cleanGit(value) {
         return null;
     return { enabled: false, ...out };
 }
-const ROOT_DEFAULTS = { repos: REPOS_DEFAULT_ROOT, vibeables: VIBEABLES_DEFAULT_ROOT, projects: PROJECTS_DEFAULT_ROOT };
-/** The repos, vibeables or projects block to write; null when the feature is off and nothing else is set. */
+const ROOT_DEFAULTS = {
+    repos: REPOS_DEFAULT_ROOT,
+    vibeables: VIBEABLES_DEFAULT_ROOT,
+    projects: PROJECTS_DEFAULT_ROOT,
+    contacts: entityDefaultRoot("contacts"),
+    places: entityDefaultRoot("places"),
+    events: entityDefaultRoot("events"),
+};
+/** The repos, vibeables, projects, contacts, places or events block to write; null when the feature is off and nothing else is set. */
 function cleanRootBlock(block, value, projectRoot) {
     if (typeof value !== "object" || value === null)
         throw new Error(`${block} must be an object`);
@@ -163,6 +171,16 @@ export async function saveSettings(input) {
         else
             doc.set("projects", projects);
     }
+    for (const kind of ENTITY_KINDS) {
+        const given = input[kind];
+        if (given === undefined)
+            continue;
+        const block = cleanRootBlock(kind, given, project.root);
+        if (block === null)
+            doc.delete(kind);
+        else
+            doc.set(kind, block);
+    }
     await fs.writeFile(configPath, doc.toString());
     // Turning repositories on prepares the folder so the first clone and the
     // workspace git both find it in the right state.
@@ -172,5 +190,8 @@ export async function saveSettings(input) {
         await ensureVibeablesRoot().catch(() => { });
     if (input.projects?.enabled)
         await ensureProjectsRoot().catch(() => { });
+    for (const kind of ENTITY_KINDS)
+        if (input[kind]?.enabled)
+            await ensureEntitiesRoot(kind).catch(() => { });
     return getSettings();
 }

package/dist/core/slug.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The one slug rule for folders and files kraftwerk names after a title:
+ * lowercase letters, digits and dashes, at most 49 characters, starting
+ * with a letter or digit. Projects, contacts, places and events share it,
+ * so a `kind:slug` reference has one shape everywhere.
+ */
+export declare const SLUG_RE: RegExp;
+/** Derive a slug from a title: "Relaunch netnode.ch" -> "relaunch-netnode-ch". */
+export declare function slugify(title: string, max?: number): string;

package/dist/core/slug.js

@@ -0,0 +1,18 @@
+/**
+ * The one slug rule for folders and files kraftwerk names after a title:
+ * lowercase letters, digits and dashes, at most 49 characters, starting
+ * with a letter or digit. Projects, contacts, places and events share it,
+ * so a `kind:slug` reference has one shape everywhere.
+ */
+export const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
+/** Derive a slug from a title: "Relaunch netnode.ch" -> "relaunch-netnode-ch". */
+export function slugify(title, max = 48) {
+    return title
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, max)
+        .replace(/-+$/, "");
+}

package/dist/core/trash.d.ts

@@ -8,7 +8,7 @@
  */
 export declare const TRASH_DIR = "kraftwerk-data/trash";
 /** What can be in the trash; also the folder under trash/ it lands in. */
-export type TrashKind = "agents" | "agent-skills" | "projects" | "workflows" | "knowledge" | "vibeables" | "channels" | "repos" | "chats" | "runs" | "files";
+export type TrashKind = "agents" | "agent-skills" | "projects" | "contacts" | "places" | "events" | "workflows" | "knowledge" | "vibeables" | "channels" | "repos" | "chats" | "runs" | "files";
 export interface TrashEntry {
     /** Path inside the trash, forward slashes — the entry's handle. */
     id: string;

package/dist/server/api/devices.js

@@ -1,4 +1,5 @@
 import * as z from "zod";
+import { log } from "../../core/log.js";
 import { createPairCode, listDevices, redeemPairCode, revokeDevice, setDevicePush } from "../../core/devices.js";
 import { networkUrls } from "../bind.js";
 import { currentHub } from "../hub-context.js";
@@ -108,7 +109,7 @@ export const deviceRoutes = [
         const { enabled, url } = await c.body();
         const s = await setRelay(enabled, url);
         const hub = currentHub();
-        const status = hub.daemon ? await applyRelay(hub.port, await getPkgVersion(), (l) => console.log(l)) : relayStatus();
+        const status = hub.daemon ? await applyRelay(hub.port, await getPkgVersion(), (level, l) => log(level, "relay", l)) : relayStatus();
         return { enabled: s.enabled, url: s.url, fingerprint: keyFingerprint(s.publicKey), daemon: hub.daemon === true, ...status };
     }),
     route({ name: "devices.revoke", method: "DELETE", path: "/api/devices/:id", summary: "unpair a device: its token stops working at once", access: "local" }, async (c) => (await revokeDevice(c.params.id)) ? { ok: true } : fail(404, "no such device")),

package/dist/server/api/entities.d.ts

@@ -0,0 +1,74 @@
+import * as z from "zod";
+import type { EntityKind } from "../../config.js";
+import { type EntityBase, type EntityKindDef } from "../../core/entities.js";
+/**
+ * Contacts, places and events over the API. One factory, three kinds: the
+ * routes are named per kind (`contacts.list`, `places.get`, `events.save`)
+ * with the kind's own result type, so the typed client and the UI see
+ * three ordinary route families — not one generic entities endpoint whose
+ * results would be a union. Adding a kind is one definition in
+ * core/entities.ts and one factory call below.
+ */
+export declare function entityRoutes<D extends EntityBase, K extends EntityKind>(def: EntityKindDef<D, K>): readonly [import("./router.js").Route<`${K}.list`, import("../../core/entities.js").EntitiesView<D>, `/api/${K}`, undefined>, import("./router.js").Route<`${K}.create`, import("./router.js").Reply<import("../../core/entities.js").EntityDetail<D>>, `/api/${K}`, z.ZodObject<{
+    notes: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    records: z.ZodOptional<z.ZodUnknown>;
+    title: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>, import("./router.js").Route<`${K}.get`, import("../../core/entities.js").EntityDetail<D>, `/api/${K}/:slug`, undefined>, import("./router.js").Route<`${K}.save`, import("../../core/entities.js").EntityDetail<D>, `/api/${K}/:slug`, z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    records: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>>, import("./router.js").Route<`${K}.delete`, {
+    ok: boolean;
+}, `/api/${K}/:slug`, undefined>];
+export declare const contactRoutes: readonly [import("./router.js").Route<"contacts.list", import("../../core/entities.js").EntitiesView<import("../../core/entities.js").ContactDef>, "/api/contacts", undefined>, import("./router.js").Route<"contacts.create", import("./router.js").Reply<import("../../core/entities.js").EntityDetail<import("../../core/entities.js").ContactDef>>, "/api/contacts", z.ZodObject<{
+    notes: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    records: z.ZodOptional<z.ZodUnknown>;
+    title: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>, import("./router.js").Route<"contacts.get", import("../../core/entities.js").EntityDetail<import("../../core/entities.js").ContactDef>, "/api/contacts/:slug", undefined>, import("./router.js").Route<"contacts.save", import("../../core/entities.js").EntityDetail<import("../../core/entities.js").ContactDef>, "/api/contacts/:slug", z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    records: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>>, import("./router.js").Route<"contacts.delete", {
+    ok: boolean;
+}, "/api/contacts/:slug", undefined>];
+export declare const placeRoutes: readonly [import("./router.js").Route<"places.list", import("../../core/entities.js").EntitiesView<import("../../core/entities.js").PlaceDef>, "/api/places", undefined>, import("./router.js").Route<"places.create", import("./router.js").Reply<import("../../core/entities.js").EntityDetail<import("../../core/entities.js").PlaceDef>>, "/api/places", z.ZodObject<{
+    notes: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    records: z.ZodOptional<z.ZodUnknown>;
+    title: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>, import("./router.js").Route<"places.get", import("../../core/entities.js").EntityDetail<import("../../core/entities.js").PlaceDef>, "/api/places/:slug", undefined>, import("./router.js").Route<"places.save", import("../../core/entities.js").EntityDetail<import("../../core/entities.js").PlaceDef>, "/api/places/:slug", z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    records: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>>, import("./router.js").Route<"places.delete", {
+    ok: boolean;
+}, "/api/places/:slug", undefined>];
+export declare const eventRoutes: readonly [import("./router.js").Route<"events.list", import("../../core/entities.js").EntitiesView<import("../../core/entities.js").EventDef>, "/api/events", undefined>, import("./router.js").Route<"events.create", import("./router.js").Reply<import("../../core/entities.js").EntityDetail<import("../../core/entities.js").EventDef>>, "/api/events", z.ZodObject<{
+    notes: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    records: z.ZodOptional<z.ZodUnknown>;
+    title: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>, import("./router.js").Route<"events.get", import("../../core/entities.js").EntityDetail<import("../../core/entities.js").EventDef>, "/api/events/:slug", undefined>, import("./router.js").Route<"events.save", import("../../core/entities.js").EntityDetail<import("../../core/entities.js").EventDef>, "/api/events/:slug", z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    records: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>>, import("./router.js").Route<"events.delete", {
+    ok: boolean;
+}, "/api/events/:slug", undefined>];
+/** References: resolve `kind:slug` tokens — given as a list, or found in a text — against the registry. */
+export declare const refRoutes: import("./router.js").Route<"refs.resolve", {
+    refs: import("../../core/refs.js").ResolvedRef[];
+}, "/api/refs/resolve", z.ZodObject<{
+    tokens: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    text: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>>[];

package/dist/server/api/entities.js

@@ -0,0 +1,60 @@
+import * as z from "zod";
+import { CONTACTS, createEntity, deleteEntity, EVENTS, getEntity, listEntities, openEntities, PLACES, saveEntity } from "../../core/entities.js";
+import { findRefs, parseRef, resolveTokens } from "../../core/refs.js";
+import { fail, reply, route, statusByMessage } from "./router.js";
+/**
+ * Contacts, places and events over the API. One factory, three kinds: the
+ * routes are named per kind (`contacts.list`, `places.get`, `events.save`)
+ * with the kind's own result type, so the typed client and the UI see
+ * three ordinary route families — not one generic entities endpoint whose
+ * results would be a union. Adding a kind is one definition in
+ * core/entities.ts and one factory call below.
+ */
+export function entityRoutes(def) {
+    const errors = statusByMessage(new RegExp(`^no ${def.singular}`));
+    const kind = def.kind;
+    /** The editable fields. Loose: the domain checks values and keeps what it knows (unknown keys stay in the frontmatter). */
+    const Fields = z.looseObject({
+        title: z.string().optional(),
+        notes: z.string().optional(),
+        tags: z.unknown().optional(),
+        records: z.unknown().optional(),
+        ...Object.fromEntries(def.fields.map((f) => [f.name, z.unknown().optional()])),
+    });
+    const Create = Fields.extend({ title: z.string(), slug: z.string().optional() });
+    const fieldNames = def.fields.map((f) => f.name).join(", ");
+    return [
+        route({ name: `${kind}.list`, method: "GET", path: `/api/${kind}`, summary: `every ${def.singular} file under the root${def.span ? " (?from=&to= narrow by date; an entry counts while it runs)" : ""}` }, async (c) => listEntities(def, { from: c.query.get("from") ?? undefined, to: c.query.get("to") ?? undefined })),
+        route({ name: `${kind}.create`, method: "POST", path: `/api/${kind}`, summary: `create one {title, slug?, notes?, tags?, records?, ${fieldNames}}`, errors: 400, body: Create }, async (c) => {
+            if ((await openEntities(kind)).off)
+                fail(409, `${kind} are off`);
+            return reply(201, await createEntity(def, (await c.body())));
+        }),
+        route({ name: `${kind}.get`, method: "GET", path: `/api/${kind}/:slug`, summary: "fields, notes and link states", errors }, async (c) => (await getEntity(def, c.params.slug)) ?? fail(404, `no ${def.singular} "${c.params.slug}"`)),
+        route({ name: `${kind}.save`, method: "PUT", path: `/api/${kind}/:slug`, summary: 'save fields and notes ("" clears a field)', errors, body: Fields }, async (c) => saveEntity(def, c.params.slug, (await c.body()))),
+        route({ name: `${kind}.delete`, method: "DELETE", path: `/api/${kind}/:slug`, summary: "move the file to the trash", errors }, async (c) => {
+            await deleteEntity(def, c.params.slug);
+            return { ok: true };
+        }),
+    ];
+}
+export const contactRoutes = entityRoutes(CONTACTS);
+export const placeRoutes = entityRoutes(PLACES);
+export const eventRoutes = entityRoutes(EVENTS);
+/** References: resolve `kind:slug` tokens — given as a list, or found in a text — against the registry. */
+export const refRoutes = [
+    route({
+        name: "refs.resolve",
+        method: "POST",
+        path: "/api/refs/resolve",
+        summary: "resolve references {tokens?: [kind:slug], text?} to whether each target exists and where it opens",
+        errors: 400,
+        body: z.object({ tokens: z.array(z.string()).default([]), text: z.string().default("") }),
+    }, async (c) => {
+        const { tokens, text } = await c.body();
+        const given = tokens.map((t) => parseRef(t) ?? fail(400, `not a reference: "${t}" (expected <kind>:<slug>, e.g. contact:anna-meier)`));
+        const found = findRefs(text);
+        const all = [...given, ...found].filter((r, i, arr) => arr.findIndex((x) => x.kind === r.kind && x.slug === r.slug) === i);
+        return { refs: await resolveTokens(all) };
+    }),
+];