@intentic/extension-manifest 1.176.3

package/src/points/viewers.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+/* A custom file viewer the extension may register at runtime (api.viewers.register): the host resolves an open
+ * file to this viewer by extension, gets its content, and renders the registered component with it — the host
+ * keeps the fetch + open-file lifecycle and the daemon credentials; the extension only renders. This is the
+ * non-sidebar contribution point. */
+export const ViewerContributionSchema = z.object({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    extensions: z
+        .array(z.string().regex(/^[a-z0-9]+$/))
+        .min(1)
+        .describe('Bare file extensions, no dot — e.g. ["docx", "xlsx"].'),
+    /* `fetch` is how much of the file the host puts in the extension's hands, and it is a real choice:
+     *   text — decoded utf8 (`text` prop). For a format that IS text: svg, a subtitle track, a notebook.
+     *   blob — the whole file in memory (`blob` prop). For a format that must be parsed end to end before any of
+     *          it can be shown: a .docx, a spreadsheet. Bounded by the daemon's raw-read cap.
+     *   url  — a streaming URL the component points an element at (`src` prop), never the bytes. For anything
+     *          RANGE-READ rather than parsed: audio and video, where the file may be gigabytes and the player
+     *          wants the header, the index and the seconds around the playhead — not the file. The host mints
+     *          the credential on that URL and keeps it out of the extension.
+     */
+    fetch: z
+        .enum(["text", "blob", "url"])
+        .describe(
+            "How much of the file the host hands you. `text` for a format that is text (svg, a subtitle track). `blob` for one that must be parsed end to end before any of it shows (a .docx, a spreadsheet) — bounded by the daemon's raw-read cap. `url` for anything range-read rather than parsed (audio, video): your component gets a streaming URL to point an element at, never the bytes.",
+        ),
+});
+export type ViewerContribution = z.infer<typeof ViewerContributionSchema>;
+
+export const viewersPoint = {
+    name: "viewers",
+    description:
+        "File formats this extension can render. The host resolves an opened file to your viewer by its extension, fetches the content, and renders your component with it — you keep none of the fetch lifecycle and none of the daemon credentials.",
+    schema: z.array(ViewerContributionSchema),
+} as const satisfies ContributionPoint;

package/src/points/views.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// A sidebar element family the extension may register at runtime (api.views.register): `rail` = a global
+// left-rail tile routed at /ext/:ext/:key?; `directory` = a per-repo panel opened from the Workspace tree;
+// `sandbox` = a tab on the Sandbox hub, for a view whose subject is the BOX rather than the work (see
+// ViewRegistration.surface).
+export const ViewContributionSchema = z.object({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    label: z.string().min(1).describe("The name shown on the tile or tab. The manifest's value wins over the one passed at registration."),
+    surface: z
+        .enum(["rail", "directory", "sandbox"])
+        .describe(
+            "Where it appears. `rail` is a tile in the global left rail; `directory` is a panel opened from a repo in the Workspace tree; `sandbox` is a tab on the Sandbox hub, for a view whose subject is the box rather than the work.",
+        ),
+    // Whether this view may badge its tile (ViewRegistration.badge). Declared here, like a command's
+    // keybinding, because it is consequential: a badge interrupts the user from every other screen in the app.
+    // Absent ⇒ the host drops any badge the extension registers.
+    badge: z
+        .boolean()
+        .optional()
+        .describe(
+            "Allow this view to put a count on its tile. Declared because a badge interrupts from every other screen in the app; leave it out and any badge the extension registers is dropped.",
+        ),
+});
+export type ViewContribution = z.infer<typeof ViewContributionSchema>;
+
+export const viewsPoint = {
+    name: "views",
+    description:
+        "Sidebar elements this extension may register at runtime. Each entry reserves an id and a surface; the extension supplies the component with api.views.register, and the host refuses any registration this list does not cover.",
+    schema: z.array(ViewContributionSchema),
+} as const satisfies ContributionPoint;

package/src/powers-diff.ts

@@ -0,0 +1,100 @@
+import type { ExtensionManifest } from "./manifest.js";
+
+/* WHAT AN UPDATE ASKS FOR, MECHANICALLY. The install dialog renders a manifest's contributions once; an update
+ * is judged on what sits BETWEEN two manifests, and "read both and compare" is exactly the job a person will
+ * skip on the fifth update. So each manifest is folded to a set of POWERS — the consequential facts an owner
+ * approved: which daemon routes it may call, which processes the daemon runs for it, what lands on the agent's
+ * PATH, what may interrupt from another screen — each under a stable key (the identity compared) with a plain
+ * sentence (what the reader sees). The diff is set arithmetic over the keys.
+ *
+ * Deliberately NOT here: plain settings (a new knob is config surface, not reach), display marks, category,
+ * version. A power's INTERNALS moving (a process's command line, a fragment's contents) keeps its key — the
+ * code changed, which is what the sha pin and the agent diff-read answer for; this diff answers only "did the
+ * set of things I approved grow". An empty `added` is what makes an update one click. */
+
+export interface PowersDiff {
+    // Powers the new manifest declares that the installed one didn't — the reason an update re-asks.
+    readonly added: string[];
+    readonly removed: string[];
+    readonly unchanged: string[];
+}
+
+const powersOf = (manifest: ExtensionManifest): Map<string, string> => {
+    const powers = new Map<string, string>();
+    if (manifest.entry !== undefined) {
+        powers.set("entry", "runs a UI bundle in your browser");
+    }
+    if (manifest.server !== undefined) {
+        powers.set("server", "runs a backend bundle inside the daemon's extension host");
+    }
+    for (const route of manifest.permissions?.sandbox ?? []) {
+        powers.set(`sandbox:${route}`, `its UI calls the sandbox route ${route}`);
+    }
+    for (const route of manifest.permissions?.daemon ?? []) {
+        powers.set(`daemon:${route}`, `its backend calls the daemon route ${route}`);
+    }
+    for (const view of manifest.contributes?.views ?? []) {
+        powers.set(`view:${view.id}`, `a ${view.surface} view "${view.label}"`);
+        if (view.badge === true) {
+            powers.set(`view-badge:${view.id}`, `may badge the "${view.label}" tile from any screen`);
+        }
+    }
+    for (const viewer of manifest.contributes?.viewers ?? []) {
+        powers.set(`viewer:${viewer.id}`, `opens .${viewer.extensions.join(", .")} files (${viewer.fetch})`);
+    }
+    for (const document of manifest.contributes?.documents ?? []) {
+        powers.set(`document:${document.id}`, `marks workspace directories ("${document.label}")`);
+    }
+    for (const command of manifest.contributes?.commands ?? []) {
+        powers.set(`command:${command.command}`, `a palette command "${command.title}"`);
+        if (command.keybinding !== undefined) {
+            powers.set(`keybinding:${command.command}`, `the global shortcut ${command.keybinding} ("${command.title}")`);
+        }
+    }
+    for (const setting of manifest.contributes?.settings ?? []) {
+        if (setting.env !== undefined) {
+            powers.set(`setting-env:${setting.key}`, `puts the "${setting.key}" setting into the agent's environment as ${setting.env}`);
+        }
+    }
+    for (const process of manifest.contributes?.processes ?? []) {
+        powers.set(`process:${process.name}`, `a background process "${process.name}"${process.autoStart === true ? " (starts on boot)" : ""}`);
+    }
+    for (const file of manifest.contributes?.files ?? []) {
+        powers.set(`files:${file.path}`, `is told when ${file.path} changes`);
+    }
+    if (manifest.contributes?.agent !== undefined) {
+        powers.set("agent", "contributes skills, agents and hooks to the agent's turns");
+    }
+    if (manifest.contributes?.environment !== undefined) {
+        powers.set("environment", "bakes an environment fragment into the sandbox image");
+    }
+    for (const capability of manifest.contributes?.capabilities ?? []) {
+        powers.set(`capability:${capability.id}`, `a ${capability.kind} capability card "${capability.catalog.name}"`);
+    }
+    if (manifest.contributes?.listener !== undefined) {
+        powers.set(`listener:${manifest.contributes.listener.provider}`, `a realtime listener provider "${manifest.contributes.listener.provider}"`);
+    }
+    if (manifest.contributes?.bin !== undefined) {
+        powers.set("bin", "puts its shipped tools on the agent's PATH");
+    }
+    return powers;
+};
+
+// `before` absent covers a first install: everything the manifest declares is `added`, which is exactly what
+// the install dialog already renders — one vocabulary for both moments.
+export const diffPowers = (before: ExtensionManifest | undefined, after: ExtensionManifest): PowersDiff => {
+    const from = before === undefined ? new Map<string, string>() : powersOf(before);
+    const to = powersOf(after);
+    const added: string[] = [];
+    const removed: string[] = [];
+    const unchanged: string[] = [];
+    for (const [key, label] of to) {
+        (from.has(key) ? unchanged : added).push(label);
+    }
+    for (const [key, label] of from) {
+        if (!to.has(key)) {
+            removed.push(label);
+        }
+    }
+    return { added, removed, unchanged };
+};