@songsid/agend 2.2.0 → 2.2.5

package/dist/web-mod-export.js

@@ -0,0 +1,100 @@
+/**
+ * #1629 r4 §4 (r4-5): building a mod bundle from what is in force — one instance's look (theme with its pictures,
+ * identity text, its widgets) and, for a person, their sidebar widget and their own CSS with its assets. The result is
+ * the same format the importer checks (web-mod-bundle.ts), and it passes that check: export → import is the round trip.
+ * Card pictures never travel (a card is an instance's identity, not a look).
+ */
+import { MEDIA_EXT } from "./web-image-meta.js";
+import { MOD_FORMAT, modFile } from "./web-mod-bundle.js";
+const enc = new TextEncoder();
+const jsonBytes = (v) => enc.encode(JSON.stringify(v, null, 2) + "\n");
+/** The bundle file's text (UTF-8 JSON), or why it can't be built (a picture the theme names is missing). */
+export function buildModBundle(meta, parts) {
+    const files = {};
+    const put = (path, bytes) => { files[path] = modFile(bytes); };
+    const contents = {};
+    if (parts.theme) {
+        const { card: _card, ...look } = parts.theme.theme;
+        void _card;
+        const out = { ...look };
+        const picture = (id, base) => {
+            const p = parts.theme.picture(id);
+            if (!p)
+                return null;
+            const path = `pictures/${base}.${MEDIA_EXT[p.kind]}`;
+            put(path, p.bytes);
+            return path;
+        };
+        if (look.background) {
+            const path = picture(look.background.image, "background");
+            if (!path)
+                return { ok: false, error: "picture_missing" };
+            out.background = { ...look.background, image: path };
+        }
+        if (look.avatar) {
+            const path = picture(look.avatar, "avatar");
+            if (!path)
+                return { ok: false, error: "picture_missing" };
+            out.avatar = path;
+        }
+        const placed = [];
+        const taken = new Set();
+        for (const e of parts.theme.effects ?? []) {
+            const base = /^[a-z0-9][a-z0-9-]{0,47}$/.test(e.name) ? e.name : "effect";
+            let slug = base;
+            for (let n = 2; taken.has(slug); n++)
+                slug = `${base}-${n}`;
+            taken.add(slug);
+            const dir = `effects/${slug}`;
+            for (const [rel, bytes] of e.files)
+                put(`${dir}/${rel}`, bytes);
+            (contents.effects ??= []).push(dir);
+            placed.push({ effect: dir, ...(Object.keys(e.params).length ? { params: e.params } : {}) });
+        }
+        if (placed.length)
+            out.effects = placed;
+        put("theme.json", jsonBytes(out));
+        contents.theme = "theme.json";
+    }
+    if (parts.identity && (parts.identity.tagline || parts.identity.bio)) {
+        put("identity.json", jsonBytes({ ...(parts.identity.tagline ? { tagline: parts.identity.tagline } : {}), ...(parts.identity.bio ? { bio: parts.identity.bio } : {}) }));
+        contents.identity = "identity.json";
+    }
+    for (const [slot, w] of Object.entries(parts.widgets ?? {})) {
+        const path = `widgets/${slot.replace("_", "-")}.json`;
+        put(path, jsonBytes({ spec: w.spec, data: w.data }));
+        (contents.widgets ??= {})[slot] = path;
+    }
+    if (parts.ambient && Object.keys(parts.ambient.specs).length) {
+        const out = {};
+        for (const [kind, spec] of Object.entries(parts.ambient.specs)) {
+            const glyphs = [];
+            for (const g of spec.glyphs) {
+                if (typeof g === "string") {
+                    glyphs.push(g);
+                    continue;
+                }
+                const p = parts.ambient.picture(g.asset);
+                if (!p)
+                    return { ok: false, error: "picture_missing" };
+                const path = `glyphs/${g.asset}.${MEDIA_EXT[p.kind]}`;
+                put(path, p.bytes);
+                glyphs.push({ asset: path });
+            }
+            out[kind] = { ...spec, glyphs };
+        }
+        put("ambient.json", jsonBytes(out));
+        contents.ambient = "ambient.json";
+    }
+    if (parts.ownerCss) {
+        // The CSS names its assets as url("asset:<id>"): the id is the hash of the kept bytes, the same on import.
+        const assets = parts.ownerCss.assets.map(a => { const path = `css/assets/${a.id}.${MEDIA_EXT[a.kind]}`; put(path, a.bytes); return path; });
+        put("css/custom.css", enc.encode(parts.ownerCss.text));
+        contents.ownerCss = { css: "css/custom.css", ...(assets.length ? { assets } : {}) };
+    }
+    if (!Object.keys(contents).length)
+        return { ok: false, error: "nothing_to_export" };
+    const manifest = { name: meta.name, version: meta.version, title: meta.title, ...(meta.description ? { description: meta.description } : {}), ...(meta.author ? { author: meta.author } : {}), contents };
+    return { ok: true, text: JSON.stringify({ format: MOD_FORMAT, v: 1, manifest, files }) + "\n", filename: `${meta.name}-${meta.version}.agendmod.json` };
+}
+//# sourceMappingURL=web-mod-export.js.map

package/dist/web-mod-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-mod-export.js","sourceRoot":"","sources":["../src/web-mod-export.ts"],"names":[],"mappings":"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"}

package/dist/web-mod-store.d.ts

@@ -0,0 +1,289 @@
+import { type CheckedMod, type EffectFiles, type ModContext, type ModProblem } from "./web-mod-bundle.js";
+import type { ThemeStore } from "./web-theme-store.js";
+import type { OwnerCssSnapshot } from "./web-owner-css-store.js";
+export declare const MOD_STAGE_MS: number;
+export declare const MODS_MAX_INSTALLED = 20;
+export declare const MODS_MAX_BYTES: number;
+/** Who an effect claim belongs to (CW1): a mod import is always a person's. */
+export interface EffectPrincipal {
+    kind: "agent" | "human";
+    id: string;
+}
+/**
+ * The effect library (Sol's B2, CW1), as mods use it. Null while the fleet has none: then no bundle with effects is
+ * accepted (the checker refuses it first).
+ */
+export interface ModEffectLibrary {
+    stage(entries: readonly EffectFiles[], principal: EffectPrincipal, opts: {
+        holder: string;
+    }): {
+        ok: true;
+        stageId: string;
+        ids: string[];
+    } | {
+        ok: false;
+        error: string;
+    };
+    commit(stageId: string): {
+        ok: true;
+        ids: string[];
+        created: string[];
+        undo: () => boolean;
+    } | {
+        ok: false;
+        error: string;
+    };
+    abort(stageId: string): void;
+    releaseHolder(holder: string, principal: EffectPrincipal): {
+        ok: true;
+        released: string[];
+        undo: () => boolean;
+    } | {
+        ok: false;
+        error: string;
+    };
+    /** A guarded, deferred collector: rechecks every claim and reference before deleting (never synchronously). */
+    collectUnreferenced?(ids: readonly string[]): void;
+}
+/** A person's preferences, as the import writes their sidebar widget (web-prefs.ts). */
+export interface ModPrefs {
+    read(identity: string): {
+        values: Record<string, unknown>;
+        unreadable?: true;
+    };
+    write(identity: string, patch: Map<string, unknown>): {
+        ok: true;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+    };
+}
+/** A person's own CSS (web-owner-css-store.ts), as the import adds its assets and tries its text. */
+export interface ModOwnerCss {
+    snapshot(person: string): OwnerCssSnapshot;
+    restoreSnapshot(person: string, snap: OwnerCssSnapshot): {
+        ok: boolean;
+    };
+    addAsset(person: string, bytes: Uint8Array): {
+        ok: true;
+        id: string;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+        detail?: string;
+    };
+    save(person: string, text: unknown): {
+        ok: true;
+        sha: string;
+        previous: string | null;
+        trial: string;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+        detail?: string;
+    };
+}
+export interface ModRecord {
+    name: string;
+    version: string;
+    title: string;
+    bytes: number;
+    installedBy: string;
+    /** Principal that owns this mod's effect holder. Older records use installedBy. */
+    effectsBy?: string;
+    installedAt: number;
+    /** The instance the look went to, when it had one. */
+    target?: string;
+    /** What was applied: "theme", "identity", "widget:<slot>", "ambient", "effects", "ownerCss". */
+    parts: string[];
+    /** The effect entries it carries, by path, and the library's ids for them (audit: which claims this commit created). */
+    effects: Array<{
+        path: string;
+        id: string;
+    }>;
+    created: string[];
+}
+export type ModWrite<T = Record<never, never>> = ({
+    ok: true;
+} & T) | {
+    ok: false;
+    status: number;
+    error: string;
+    detail?: string;
+    problems?: ModProblem[];
+};
+export interface ModPlanItem {
+    part: string;
+    [k: string]: unknown;
+}
+export interface ModPlan {
+    mod: {
+        id: string;
+        name: string;
+        version: string;
+        title: string;
+        description?: string;
+        author?: string;
+        requires?: string;
+        bytes: number;
+        installed: boolean;
+        replaces?: {
+            id: string;
+            version: string;
+        };
+    };
+    items: ModPlanItem[];
+    /** Whether a target instance must be chosen (a theme, identity, agent widgets or effect placements). */
+    needs_target: boolean;
+    warnings: string[];
+}
+export interface ModInclude {
+    theme?: boolean;
+    identity?: boolean;
+    effects?: boolean;
+    ownerCss?: boolean;
+    ambient?: boolean;
+    widgets?: Partial<Record<"chat_header" | "details" | "sidebar", boolean>>;
+    /** Replace the installed mod of the same name (a different version). */
+    replace?: boolean;
+}
+/** r4-5b: a mod an agent proposed (propose_web_mod), waiting for a person to review it — one per agent. */
+export interface ModProposal {
+    name: string;
+    version: string;
+    title: string;
+    bytes: number;
+    at: number;
+    id: string;
+}
+export declare const modHolder: (id: string) => string;
+/** What the page shows before anything is applied: every part, in full (the owner CSS's text included). */
+export declare function modPlan(mod: CheckedMod, installed: ReadonlyMap<string, ModRecord>): ModPlan;
+export declare class ModStore {
+    private readonly dataDir;
+    private readonly deps;
+    private index;
+    private readonly stages;
+    readonly path: string;
+    constructor(dataDir: string, deps: {
+        themes: ThemeStore;
+        prefs: ModPrefs;
+        ownerCss: ModOwnerCss | null;
+        effects: ModEffectLibrary | null;
+        context: () => ModContext;
+        isKnownInstance: (name: string) => boolean;
+        /** The preferences bucket the page reads (/ui/prefs: one, the operator's — web-prefs.ts). */
+        prefsIdentity: string;
+        clock?: () => number;
+        now?: () => number;
+    });
+    private clock;
+    private now;
+    private file;
+    private load;
+    private save;
+    /** Write the index (disk first, then memory). `proposals`: unchanged unless given. */
+    private commitIndex;
+    private proposalFile;
+    /**
+     * r4-5b: keep an agent's proposed mod (checked already, and never carrying custom CSS — the caller refuses that by
+     * the path the bytes came in by) until a person reviews or dismisses it. One per agent: a new one replaces it.
+     */
+    propose(instance: string, text: string, mod: CheckedMod): ModWrite<{
+        proposal: ModProposal;
+    }>;
+    /** Proposals waiting for a person, by agent. */
+    proposals(): Array<ModProposal & {
+        instance: string;
+    }>;
+    /** A person opens an agent's proposal into the usual review: staged as theirs, its plan shown in full. */
+    stageProposal(person: string, instance: unknown): ModWrite<{
+        stage: string;
+        plan: ModPlan;
+        plan_hash: string;
+    }>;
+    /** A person dismisses an agent's proposal. */
+    dismiss(instance: unknown): ModWrite;
+    /** The context bundles are checked in (the effect runtime's checker, when the fleet has one): the agent's side uses it too. */
+    checkContext(): ModContext;
+    /** Installed mods, for the page. */
+    list(): {
+        rev: number;
+        mods: Array<ModRecord & {
+            id: string;
+        }>;
+        unreadable?: true;
+    };
+    /** An installed bundle's file, exactly as it was checked (for export of an installed mod). */
+    bundleText(id: string): string | null;
+    /**
+     * The effects an installed bundle's file carries, as library content ids — what downloading that file hands over,
+     * whether or not its import installed them (an import that left effects out still keeps the whole file). "unknown":
+     * the file no longer checks here and lists effects, so what they are can't be said; null: no such mod.
+     */
+    bundleEffects(id: string): string[] | "unknown" | null;
+    /** Stages left idle past their time go (their effect stage is aborted). */
+    private sweep;
+    private drop;
+    /** The person's staged import (its plan), if one is still current. */
+    staged(person: string): {
+        stage: string;
+        plan: ModPlan;
+        plan_hash: string;
+        expires_in_s: number;
+    } | null;
+    /** #2064 review: where the person's open review came from — an agent's proposal (its instance) or a file (null). */
+    stageOrigin(person: string): {
+        stage: string;
+        proposal: string | null;
+    } | null;
+    /** A picture of this person's staged mod (its theme's), so the plan can show it before anything is applied. */
+    stagedPicture(person: string, id: string): {
+        bytes: Uint8Array;
+        mime: string;
+    } | null;
+    abort(person: string, stage: unknown): ModWrite;
+    /**
+     * Step 1: check the uploaded file whole and keep it, with its plan, for this person (one stage each: a new one
+     * replaces theirs). Nothing is applied.
+     */
+    stage(person: string, text: string, from?: {
+        proposal?: string;
+    }): ModWrite<{
+        stage: string;
+        plan: ModPlan;
+        plan_hash: string;
+    }>;
+    /**
+     * Step 2: apply exactly the staged plan's chosen parts, atomically. `person`: the signed-in session's person (their
+     * own CSS goes to them); the sidebar widget is a preference of the page's one bucket. A changed plan hash is 409; an
+     * unknown or expired stage is 404.
+     */
+    commit(person: string, body: {
+        stage?: unknown;
+        plan_hash?: unknown;
+        include?: unknown;
+        target?: unknown;
+    }): ModWrite<{
+        id: string;
+        applied: string[];
+        css?: {
+            trial: string;
+            sha: string;
+            previous: string | null;
+        };
+    }>;
+    /** Remove an installed mod from the library: its effect claim, its file and its entry. What it applied stays. */
+    uninstall(id: unknown): ModWrite<{
+        released: string[];
+    }>;
+    /** An instance was removed: its name leaves the records that named it as their target. */
+    forgetInstance(name: string): void;
+    /** Tests: the folder bundles live in. */
+    get folder(): string;
+    /** Every installed bundle's file is removed with the index (tests and a reset). */
+    clear(): void;
+}