@sigrun/sigrun 0.6.0 → 0.7.0

package/dist/server/core-views/skills-tree.js

@@ -0,0 +1,628 @@
+/**
+ * The `core/skills` view's PURE tree builders (tabs+skills Task 12):
+ * no I/O, no process state — sidebar rows, the data document, and the
+ * page tree as pure functions of their inputs, so the tree suite pins
+ * them without a server (and the 3000-commit case stays cheap).
+ *
+ * The tree is DATA-BOUND (the Task 4 bump contract): every list binds
+ * `{$: ...}` against the data document; `bumpAllInstances("core",
+ * "skills")` after any write refetches data against an unchanged tree.
+ * Per-row drill-in rides the `edit`+`{itemId}` activation (`openSkill`
+ * / `openCommit` handlers return the navigate — navigate params are
+ * static literals and can never carry the activated row's id; the
+ * core/jobs Critical-2 pattern). Actions live ONLY on blocks whose
+ * contract carries them: `page`, `callout`, and card templates.
+ */
+/** The history page size (the brief's 25-per-page rule). */
+export const SKILLS_HISTORY_PAGE_SIZE = 25;
+/**
+ * Sidebar group ids, in display order (the brief's grouping).
+ * Whole-branch review I5 — the spec's semantics: the `<configDir>/skills`
+ * root groups under **Config dir**; package skills get PER-PACKAGE groups
+ * appended after the declared ones (the collection contract tolerates
+ * unknown group keys — webui, TUI and the text renderer all title an
+ * undeclared group by its key, so the key IS the display string:
+ * `· <pkg>`). Workspace / Learned / Deleted are unchanged.
+ */
+export const SKILL_GROUPS = [
+    "workspace",
+    "learned",
+    "config-dir",
+    "deleted",
+];
+/** One package skill's per-package group key — `· <pkg>`. Undeclared
+ *  groups render under their key, so the key doubles as the title. */
+export function packageGroupKey(pkg) {
+    return `· ${pkg}`;
+}
+/** The group titles for the DECLARED groups. */
+export const GROUP_TITLES = {
+    workspace: "Workspace",
+    learned: "Learned",
+    "config-dir": "Config dir",
+    deleted: "Deleted",
+};
+/**
+ * The TOTAL bytes one commit's inlined before+after texts may occupy
+ * across ALL files (whole-branch review I6): `changes()` caps each side
+ * per file at 64 KiB, but a many-file commit could still blow the 4 MiB
+ * view cap and 500 the tab. Beyond this budget the remaining files are
+ * replaced by ONE elision marker row.
+ */
+export const SKILLS_COMMIT_TOTAL_BYTES = 512 * 1024;
+/** The elision marker text (the tree pins it; the UI shows it). */
+export function elidedMarker(omitted) {
+    return `diff truncated — ${omitted} more file${omitted === 1 ? "" : "s"}`;
+}
+/**
+ * Cap a commit's files to the total inline budget (review I6): files
+ * embed in path order until the running before+after total would pass
+ * {@link SKILLS_COMMIT_TOTAL_BYTES}; the rest collapse into one marker
+ * row. A single file always embeds (its sides are already per-file
+ * capped at 64 KiB) — the budget is checked BETWEEN files, never
+ * against the first.
+ */
+export function capCommitFiles(files) {
+    let total = 0;
+    const kept = [];
+    for (const file of files) {
+        const size = file.before.length + file.after.length;
+        if (kept.length > 0 && total + size > SKILLS_COMMIT_TOTAL_BYTES)
+            break;
+        kept.push(file);
+        total += size;
+    }
+    const omitted = files.length - kept.length;
+    if (omitted === 0)
+        return kept;
+    return [
+        ...kept,
+        { path: elidedMarker(omitted), before: "", after: "", elided: true },
+    ];
+}
+/** A non-empty string, or undefined (bad types drop). */
+function stringOf(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/** Parse the instance params (loose JSON → the typed shape). */
+export function skillsParamsOf(params) {
+    const out = {};
+    const skill = stringOf(params.skill);
+    const root = stringOf(params.root);
+    const pkg = stringOf(params.pkg);
+    const commit = stringOf(params.commit);
+    const cursor = stringOf(params.cursor);
+    if (skill !== undefined)
+        out.skill = skill;
+    if (root === "workspace" ||
+        root === "learned" ||
+        root === "user dir" ||
+        root === "package") {
+        out.root = root;
+    }
+    if (pkg !== undefined)
+        out.pkg = pkg;
+    if (commit !== undefined)
+        out.commit = commit;
+    if (cursor !== undefined)
+        out.cursor = cursor;
+    if (params.edit === true)
+        out.edit = true;
+    return out;
+}
+/** The brief's instance key: principal-scoped, params-folded. */
+export function skillsInstanceKey(params, principal) {
+    return JSON.stringify([principal.user ?? "", params]);
+}
+/** The row id an activated sidebar card reports as `{itemId}` (stable, parseable). */
+export function rowIdOf(root, name, pkg) {
+    return `${root}:${name}${pkg === undefined ? "" : `:${pkg}`}`;
+}
+/** Parse a sidebar row id back into its root/name/pkg (undefined on a foreign shape). */
+export function parseRowId(id) {
+    const root = id.startsWith("workspace:")
+        ? "workspace"
+        : id.startsWith("learned:")
+            ? "learned"
+            : id.startsWith("user dir:")
+                ? "user dir"
+                : id.startsWith("package:")
+                    ? "package"
+                    : undefined;
+    if (root === undefined)
+        return undefined;
+    const rest = id.slice(root.length + 1);
+    if (rest === "")
+        return undefined;
+    if (root !== "package")
+        return { root, name: rest };
+    const at = rest.lastIndexOf(":");
+    if (at <= 0)
+        return undefined;
+    const pkg = rest.slice(at + 1);
+    const name = rest.slice(0, at);
+    return pkg === "" || name === "" ? undefined : { root, name, pkg };
+}
+/** One skill's sidebar group (a per-package id for package skills). */
+export function groupOfRow(skill, deleted) {
+    if (deleted)
+        return "deleted";
+    switch (skill.root) {
+        case "workspace":
+            return "workspace";
+        case "learned":
+            return "learned";
+        // Review I5: the spec's semantics — `<configDir>/skills` IS the
+        // Config dir group; a package skill groups under its own package.
+        case "user dir":
+            return "config-dir";
+        case "package":
+            return packageGroupKey(skill.packageName ?? "unknown");
+    }
+}
+/** The data rows the sidebar collection binds (grouped by {@link groupOfRow}). */
+export function sidebarRows(skills, opts) {
+    const deleted = opts?.deleted ?? new Set();
+    return skills.map((skill) => ({
+        id: rowIdOf(skill.root, skill.name, skill.packageName),
+        name: skill.name,
+        description: skill.description,
+        group: groupOfRow(skill, deleted.has(skill.name)),
+        ...(skill.packageName === undefined ? {} : { pkg: skill.packageName }),
+        ...(skill.shadowedBy === undefined
+            ? {}
+            : { shadowedBy: `shadowed by ${skill.shadowedBy}` }),
+        ...(skill.hidden ? { hidden: true } : {}),
+        ...(skill.error === undefined ? {} : { error: skill.error }),
+    }));
+}
+/** The ordered `groups` declaration. The DECLARED groups order the
+ *  sidebar; per-package groups (`· <pkg>`) are undeclared and append
+ *  after them, rendered under their key (the collection contract
+ *  tolerates unknown group keys). */
+function sidebarGroups() {
+    return [
+        { id: "workspace", title: "Workspace" },
+        { id: "learned", title: "Learned" },
+        { id: "config-dir", title: "Config dir" },
+        { id: "deleted", title: "Deleted" },
+    ];
+}
+/** One history row (curator commits flag the review navigation). */
+export function historyRowOf(commit) {
+    const curator = commit.actor.kind === "curator" || commit.reviewId !== undefined;
+    return {
+        id: commit.sha,
+        sha: commit.sha,
+        at: commit.at,
+        summary: commit.summary,
+        author: commit.actor.kind === "user" ? commit.actor.user : commit.actor.kind,
+        ...(curator ? { curator: true } : { curator: false }),
+        ...(commit.reviewId === undefined ? {} : { reviewId: commit.reviewId }),
+    };
+}
+/** The history page for the data document (the brief's 25-per-page + cursor). */
+export function historyPage(commits) {
+    const page = commits.slice(0, SKILLS_HISTORY_PAGE_SIZE).map(historyRowOf);
+    const last = page[page.length - 1];
+    return {
+        items: page,
+        hasMore: commits.length > SKILLS_HISTORY_PAGE_SIZE,
+        nextCursor: last === undefined ? null : last.sha,
+    };
+}
+/** Whether the caller can write the selected root (the view's surface access). */
+export function canWrite(selection, historyAvailable) {
+    if (selection === undefined)
+        return true;
+    if (selection.root === "workspace")
+        return historyAvailable;
+    return selection.root === "learned";
+}
+/** One history card's action buttons (per-row literals — navigate params cannot bind). */
+function historyRowButtons(rows) {
+    const out = [];
+    for (const row of rows) {
+        if (row.curator && row.reviewId !== undefined) {
+            out.push({
+                id: `curator-${row.sha}`,
+                label: "Review",
+                icon: "link",
+                action: {
+                    type: "navigate",
+                    target: {
+                        view: { extension: "curator", id: "curator", params: { review: row.reviewId } },
+                    },
+                },
+            });
+        }
+    }
+    return out;
+}
+/** One selected-skill callout's action buttons (per-page literals; handlers resolve params). */
+function skillActions(params, historyAvailable, deleted) {
+    // A deleted selection (whole-branch review I2): NO edit/delete/restore
+    // — the dir is gone (Edit's save would error "skill not found") — only
+    // the restore-deleted affordance, anchored on the selection's commit.
+    if (deleted) {
+        if (params.commit === undefined || !historyAvailable)
+            return [];
+        return [
+            {
+                id: "skill-restore-deleted",
+                label: "Restore deleted",
+                icon: "refresh",
+                action: {
+                    type: "submit",
+                    name: "restoreDeleted",
+                    confirm: {
+                        title: "Restore this deleted skill?",
+                        body: "Bring the skill back exactly as it was before the deletion commit.",
+                    },
+                },
+            },
+        ];
+    }
+    const nav = (extra) => {
+        const navParams = {};
+        if (params.skill !== undefined)
+            navParams.skill = params.skill;
+        if (params.root !== undefined)
+            navParams.root = params.root;
+        if (params.pkg !== undefined)
+            navParams.pkg = params.pkg;
+        for (const [key, value] of Object.entries(extra)) {
+            if (value === true || typeof value === "string")
+                navParams[key] = value;
+        }
+        return { type: "navigate", params: navParams };
+    };
+    // Read-only roots (user dir / package) are overlay-only: no edit,
+    // no delete, no restore — the caller never owns those files.
+    if (params.root === "user dir" || params.root === "package") {
+        return [
+            {
+                id: "skill-overlay",
+                label: "Write an overlay",
+                icon: "edit",
+                action: { type: "submit", name: "overlayPut" },
+            },
+            {
+                id: "skill-overlay-remove",
+                label: "Remove the overlay",
+                icon: "delete",
+                action: {
+                    type: "submit",
+                    name: "overlayRemove",
+                    confirm: { title: "Remove the overlay?", body: "Remove your note from this skill? The skill itself is untouched." },
+                },
+            },
+        ];
+    }
+    const buttons = [
+        {
+            id: "skill-edit",
+            label: "Edit",
+            icon: "edit",
+            action: nav({ edit: true }),
+        },
+        {
+            id: "skill-delete",
+            label: "Delete",
+            icon: "delete",
+            action: {
+                type: "submit",
+                name: "delete",
+                confirm: {
+                    title: "Delete skill?",
+                    body: "Delete this skill? Its history keeps every version.",
+                    tone: "bad",
+                },
+            },
+        },
+    ];
+    if (params.root === "learned") {
+        buttons.push({
+            id: "skill-pin",
+            label: "Pin",
+            icon: "tag",
+            action: { type: "submit", name: "pin" },
+        });
+    }
+    if (params.commit !== undefined && params.root !== undefined && historyAvailable) {
+        buttons.push({
+            id: "skill-restore",
+            label: "Restore this version",
+            icon: "refresh",
+            action: {
+                type: "submit",
+                name: "restoreVersion",
+                confirm: {
+                    title: "Restore this version?",
+                    body: "Make the skill exactly as it was at this commit (a new commit records the restore).",
+                },
+            },
+        });
+    }
+    return buttons;
+}
+/** The form fields (new skill vs edit: the name is read-only on an existing skill). */
+function formFields(editingExisting) {
+    const whereChoice = {
+        type: "choice",
+        name: "where",
+        label: "Where",
+        required: true,
+        options: [
+            { id: "workspace", label: "Workspace" },
+            { id: "learned", label: "Learned" },
+        ],
+    };
+    return [
+        ...(editingExisting ? [] : [whereChoice]),
+        {
+            type: "text",
+            name: "name",
+            label: "Name",
+            required: true,
+            pattern: "^[a-z0-9][a-z0-9-]{0,62}$",
+            help: "lowercase letters, digits, dashes",
+            ...(editingExisting ? { disabled: true } : {}),
+        },
+        {
+            type: "text",
+            name: "description",
+            label: "Description",
+            required: true,
+        },
+        {
+            type: "longtext",
+            name: "body",
+            label: "Body",
+            syntax: "markdown",
+            rows: 16,
+        },
+    ];
+}
+/** The anonymous/none-access tree (an empty page; the route 404s it). */
+export function skillsNoneTree() {
+    // SAFETY: the tree object is a JSON literal built here; `Tree`'s
+    // interfaces lack the index signature the wire type requires, so the
+    // cast only restores that erased identity.
+    return {
+        v: 1,
+        root: {
+            type: "page",
+            id: "skills-root",
+            title: "Skills",
+            main: [{ type: "markdown", text: "Sign in to see skills." }],
+        },
+    };
+}
+/**
+ * The full tree for one render: the sidebar collection (bound,
+ * grouped), the main column for the selection state (list / edit form /
+ * selected skill with history + diffs), and the compact-drill-in
+ * `selection` contract (Task 3). Blocks are built as loose JSON
+ * objects; the service validates every tree before serving.
+ */
+export function buildSkillsTree(params, main, 
+// The form VALUES ride the data document (bind "/form"); the tree
+// declares the fields only — the parameter pins the signature the
+// render path fills (pre-filled edit values land in data, not the tree).
+_form, opts) {
+    const editing = params.edit === true && (params.skill === undefined || opts.selectedExists);
+    const editingExisting = editing && params.skill !== undefined;
+    const selected = !editing && params.skill !== undefined && main !== undefined;
+    const sidebar = [
+        {
+            type: "collection",
+            id: "skills",
+            display: "list",
+            items: { $: "/skills" },
+            groupBy: "group",
+            groups: sidebarGroups(),
+            // Per-row drill-in (the core/jobs Critical-2 pattern): the
+            // `edit` activation carries {itemId} (the row id) to `openSkill`,
+            // whose accepted result carries the navigate back.
+            onActivate: { type: "edit", name: "openSkill" },
+            item: {
+                title: { $: "./name" },
+                subtitle: { $: "./description" },
+                body: { $: "./error" },
+                badges: [
+                    { text: { $: "./pkg" }, tone: "neutral" },
+                    { text: { $: "./shadowedBy" }, tone: "neutral" },
+                    { text: { $: "./hidden" }, tone: "neutral" },
+                ],
+            },
+        },
+    ];
+    const mainBlocks = [];
+    if (editing) {
+        mainBlocks.push({
+            type: "form",
+            id: "skill-form",
+            bind: "/form",
+            mode: "submit",
+            onSubmit: editingExisting ? "save" : "create",
+            submitLabel: editingExisting ? "Save" : "Create",
+            children: formFields(editingExisting),
+        });
+    }
+    else if (selected && main !== undefined) {
+        const historyNav = {};
+        if (params.skill !== undefined)
+            historyNav.skill = params.skill;
+        if (params.root !== undefined)
+            historyNav.root = params.root;
+        if (params.pkg !== undefined)
+            historyNav.pkg = params.pkg;
+        mainBlocks.push({
+            type: "section",
+            id: "skill-summary",
+            title: { $: "/main/name" },
+            children: [
+                {
+                    type: "fields",
+                    rows: [
+                        { label: "Root", value: { $: "/main/root" } },
+                        { label: "Description", value: { $: "/main/description" } },
+                        { label: "Path", value: { $: "/main/rootDir" } },
+                    ],
+                },
+            ],
+        }, ...(opts.writable
+            ? [
+                {
+                    type: "callout",
+                    id: "skill-actions",
+                    tone: "neutral",
+                    title: "Actions",
+                    actions: skillActions(params, opts.historyAvailable, opts.deleted === true),
+                },
+            ]
+            : []), {
+            type: "section",
+            id: "skill-body",
+            title: "SKILL.md",
+            children: [{ type: "markdown", text: { $: "/main/body" } }],
+        }, ...(main.overlay === null
+            ? []
+            : [
+                {
+                    type: "section",
+                    id: "skill-overlay",
+                    title: "Your notes",
+                    children: [{ type: "markdown", text: { $: "/main/overlay" } }],
+                },
+            ]), {
+            type: "section",
+            id: "skill-files",
+            title: "Support files",
+            children: [
+                {
+                    type: "collection",
+                    id: "support-files",
+                    display: "list",
+                    items: { $: "/main/supportFiles" },
+                    item: { title: { $: "./" } },
+                },
+            ],
+        });
+        if (main.history.available) {
+            const rows = main.history.items;
+            const curatorButtons = historyRowButtons(rows);
+            mainBlocks.push({
+                type: "section",
+                id: "skill-history",
+                title: "History",
+                children: [
+                    {
+                        type: "collection",
+                        id: "history",
+                        display: "list",
+                        items: { $: "/main/history/items" },
+                        onActivate: { type: "edit", name: "openCommit" },
+                        item: {
+                            title: { $: "./summary" },
+                            subtitle: { $: "./author" },
+                            meta: [{ time: { $: "./at" }, format: "relative" }],
+                            badges: [{ text: { $: "./curator" }, tone: "neutral" }],
+                            ...(curatorButtons.length === 0 ? {} : { actions: curatorButtons }),
+                        },
+                    },
+                ],
+            });
+            if (main.history.hasMore && main.history.nextCursor !== null) {
+                mainBlocks.push({
+                    type: "callout",
+                    id: "history-more",
+                    tone: "neutral",
+                    title: "More history",
+                    actions: [
+                        {
+                            id: "history-more-load",
+                            label: "Load more",
+                            icon: "more",
+                            action: {
+                                type: "navigate",
+                                params: { ...historyNav, cursor: main.history.nextCursor },
+                            },
+                        },
+                    ],
+                });
+            }
+        }
+        else {
+            mainBlocks.push({
+                type: "callout",
+                id: "history-unavailable",
+                tone: "neutral",
+                title: "History unavailable",
+                body: { $: "/main/history/reason" },
+            });
+        }
+        // The selected commit: one `diff` block per changed file. The
+        // elision marker row (review I6's total-bytes cap) renders as a
+        // markdown note, not a diff.
+        if (main.commit !== null) {
+            const files = main.commit.files.map((file, index) => file.elided === true
+                ? { type: "markdown", id: `commit-elided-${index}`, text: `_${file.path}_` }
+                : {
+                    type: "diff",
+                    id: `commit-diff-${index}`,
+                    before: file.before,
+                    after: file.after,
+                    lang: "markdown",
+                });
+            mainBlocks.push({
+                type: "section",
+                id: "commit-section",
+                title: `Commit ${main.commit.sha.slice(0, 8)}`,
+                children: files.length === 0
+                    ? [{ type: "markdown", text: "No changes to this skill in this commit." }]
+                    : files,
+            });
+        }
+    }
+    else {
+        mainBlocks.push({
+            type: "section",
+            id: "skill-empty",
+            children: [{ type: "markdown", text: "Select a skill" }],
+        });
+    }
+    // SAFETY: the tree object is a JSON literal built here; `Tree`'s
+    // interfaces lack the index signature the wire type requires, so the
+    // cast only restores that erased identity.
+    return {
+        v: 1,
+        root: {
+            type: "page",
+            id: "skills-root",
+            title: "Skills",
+            ...(opts.writable
+                ? {
+                    actions: [
+                        {
+                            id: "skill-new",
+                            label: "New skill",
+                            icon: "add",
+                            action: { type: "navigate", params: { edit: true } },
+                        },
+                    ],
+                }
+                : {}),
+            sidebar,
+            main: mainBlocks,
+            selection: {
+                selected: editing || (params.skill !== undefined && opts.selectedExists),
+                back: {},
+            },
+            ...(params.skill !== undefined && !editing && !opts.selectedExists
+                ? { empty: { icon: "info", title: "Skill not found" } }
+                : {}),
+        },
+    };
+}