@intentic/extension-manifest 1.248.0 → 1.249.0

package/src/points/files.ts

@@ -1,25 +1,12 @@
 import { z } from "zod";
 import type { ContributionPoint } from "../contribution-point.js";
 
-/* WHICH WORKSPACE FILE MAKES THIS EXTENSION'S VIEW STALE, the extension's half of the core's
- * WORKSPACE_STATE_FILES table (@intentic/sandbox-contract), in the same two fields so the browser can union them
- * without translating.
- *
- * An intentic workspace is file-first: the agent edits /work with its own file tools, out of band from every
- * HTTP route, and the daemon's filesystem watcher is the ONLY thing that can tell a browser its view went stale.
- * Before this contribution point existed an extension had no way into that push, so every one of them polled,
- * and the core's table had to hardcode `automations`/`automation-approvals`, query keys owned by an extension,
- * because the extension itself couldn't declare them. Declaring is now the extension's job and unioning is the
- * host's.
- *
- * It rides the manifest rather than a runtime api.workspace.onDidChangeFiles for two reasons: the owner sees at
- * install which of their files an extension reads, and there is nothing imperative left to get wrong, no
- * subscribe, no unsubscribe, no listener that quietly stops firing. */
+// Which workspace file makes this extension's view stale; the extension's half of the core's WORKSPACE_STATE_FILES
+// table (@intentic/sandbox-contract), same two fields so the browser can union them without translating. Rides the
+// manifest rather than a runtime subscription, so the owner sees at install which files an extension reads.
 export const FileContributionSchema = z.object({
-    /* Workspace-root-relative, forward-slash, the space the watcher's changed paths arrive in. Matched by
-     * PREFIX, so one entry covers an exact file (`.intentic/config/automations.json`), a directory (`.intentic/config/approvals/`
-     *, keep the trailing slash so it cannot match a sibling file) or a name family (`.intentic/environment.`).
-     * Deliberately not a glob: prefix is the whole matching rule on both sides of this union. */
+    // Workspace-root-relative, forward-slash, matched by prefix: covers an exact file, a directory (keep the trailing
+    // slash), or a name family. Not a glob.
     path: z
         .string()
         .min(1)
@@ -29,14 +16,8 @@ export const FileContributionSchema = z.object({
         .describe(
             "Workspace-root-relative, forward-slash, matched by prefix, so one entry covers an exact file (`.intentic/config/automations.json`), a directory (`.intentic/config/approvals/`, with the trailing slash so it cannot match a sibling file) or a name family (`.intentic/environment.`). Not a glob.",
         ),
-    /* The browser query keys those contents feed, the first element of the extension's own
-     * `api.sandbox.key(...)` keys, which is what makes them match (the sandbox id is a SUFFIX). Empty is not
-     * allowed: a path that makes nothing stale is a declaration with no effect, and saying so at install beats
-     * discovering it as a view that never refreshes.
-     *
-     * Keep the paths as narrow as the view actually needs. A broad prefix costs every connected browser a
-     * refetch per matching write, and a write-heavy path (an index, a transcript, a log) turns that into a
-     * request storm, the reason the core table leaves the daemon's own machine state off the push entirely. */
+    // The browser query keys this path's contents feed. Keep both this and the path as narrow as the view actually
+    // needs; a broad prefix costs every connected browser a refetch per matching write.
     invalidates: z
         .array(z.string().min(1))
         .min(1)

package/src/points/index.ts

@@ -28,17 +28,9 @@ export * from "./settings.js";
 export * from "./viewers.js";
 export * from "./views.js";
 
-/* EVERYTHING A MANIFEST MAY DECLARE. `contributes` is assembled from this list (manifest.ts), the authoring
- * JSON Schema is generated from it (json-schema.ts), and the SDK's surface guard reads the point names back out
- * of it, so the three cannot disagree about what this build supports.
- *
- * Collected explicitly rather than by a module-load side effect, because two readers need the answer to be the
- * same every time it is asked: the wire contract's lock file, which is a committed document a diff has to be
- * able to guard, and the generated schema, which is committed too. A registry that filled itself as modules
- * happened to load would make both of those depend on import order.
- *
- * Adding a point is a file in this directory and a line here, points.test.ts fails when a file appears without
- * the line, so the pair cannot come apart. */
+// Everything a manifest may declare. `contributes` (manifest.ts), the authoring schema (json-schema.ts) and the SDK's
+// surface guard are all generated from this list, so the three can't disagree about what this build supports. Adding a
+// point is a file plus a line here; points.test.ts fails if they come apart.
 export const CONTRIBUTION_POINTS = [
     viewsPoint,
     filesPoint,
@@ -55,19 +47,14 @@ export const CONTRIBUTION_POINTS = [
     binPoint,
 ] as const satisfies readonly ContributionPoint[];
 
-// The `contributes` shape those points assemble to: each point's key, its schema, optional. A mapped type
-// rather than a widened record so `manifest.contributes.views` keeps its exact type at every call site, the
-// whole point of the schema being typed at all.
+// The `contributes` shape those points assemble to. A mapped type rather than a widened record, so
+// `manifest.contributes.views` keeps its exact type at every call site.
 type ContributesShape = {
     [Point in (typeof CONTRIBUTION_POINTS)[number] as Point["name"]]: z.ZodOptional<Point["schema"]>;
 };
 
-/* The `contributes` object, assembled rather than hand-written, which is what makes adding a point a file plus
- * a line above, instead of an edit to a schema thirteen unrelated features share.
- *
- * Each point's description rides `z.describe` onto its own key, so it survives into the generated authoring
- * schema and reaches the author as hover text. The cast is the one place the value side and the type side meet:
- * `Object.fromEntries` can only say `Record<string, …>`, and ContributesShape is that said precisely. */
+// The `contributes` object, assembled rather than hand-written, so adding a point is a file plus a line above. Each
+// point's description rides `z.describe` onto its own key, reaching the generated authoring schema as hover text.
 export const contributesSchema = z.object(
     Object.fromEntries(CONTRIBUTION_POINTS.map((point) => [point.name, point.schema.describe(point.description).optional()])) as ContributesShape,
 );

package/src/points/listener.ts

@@ -1,30 +1,19 @@
 import { z } from "zod";
 import type { ContributionPoint } from "../contribution-point.js";
 
-// One narrowing field the generic automation editor draws for a source, a channel, a branch. `hint` is the
-// sentence under the input, for a filter whose empty case is easy to get wrong.
+// One narrowing field the generic automation editor draws for a source (a channel, a branch).
 const TriggerFieldContributionSchema = z.object({
     label: z.string().min(1),
     placeholder: z.string().min(1),
     hint: z.string().min(1).optional().describe("The sentence under the input, for a filter whose empty case is easy to get wrong."),
 });
 
-/* A realtime listener source the extension supplies. This is the ONE catalog both halves consume: the daemon
- * derives its accepted event types from `events` and folds `automation` into the trigger catalogue it serves,
- * while the automation editor derives the source picker, filters and starter from that. Keeping those facts on
- * the provider extension is what lets a newly installed listener become configurable without a matching app
- * release.
- *
- * The daemon serves a provider-scoped control surface. GET /listeners/<provider>/state to reconcile, POST
- * …/dispatch to wake an automation (optionally holding a turn-stream), …/failure + …/status to report. The
- * daemon holds no provider connection itself.
- *
- * WHAT DISPATCHES IT IS OPEN. A gateway process (contributes.processes) is the usual answer and the one the
- * reconcile feed is shaped for, it holds a live connection the daemon must not. But an extension BACKEND can
- * dispatch through the same route by declaring the dispatch path in `permissions.daemon`, which is
- * how an area that learns things on its own schedule (an estate poller noticing a container died) contributes
- * a trigger without running a gateway at all. Declaring this with neither is legal and inert: the source is
- * offered, and nothing ever fires it. */
+// A realtime listener source the extension supplies: the daemon derives its accepted event types from `events` and
+// folds `automation` into the trigger catalogue; the automation editor derives its source picker, filters and starter
+// from the same data. The daemon serves a provider-scoped control surface (GET/POST /listeners/<provider>/...) and
+// holds no provider connection itself. What dispatches it is open: a gateway process is the usual answer, but an
+// extension backend may dispatch through the same route via `permissions.daemon`. Declaring this with neither is legal
+// and inert.
 export const ListenerContributionSchema = z.object({
     provider: z
         .string()
@@ -45,8 +34,8 @@ export const ListenerContributionSchema = z.object({
     automation: z
         .object({
             label: z.string().min(1),
-            // Only sources whose `message` events distinguish addressed messages declare this. Absent means the
-            // generic editor offers no mention-only filter rather than inventing provider semantics.
+            // Only for a source whose message events distinguish being addressed; absent ⇒ no mention-only filter
+            // offered.
             mentionLabel: z
                 .string()
                 .min(1)
@@ -55,9 +44,8 @@ export const ListenerContributionSchema = z.object({
                     "Only for a source whose message events distinguish being addressed. Absent ⇒ the editor offers no mention-only filter, rather than inventing semantics you did not promise.",
                 ),
             channel: TriggerFieldContributionSchema.describe("The primary narrowing filter, a channel, a room, a repo."),
-            // A SECOND narrowing axis, for a source whose events carry one, a pipeline's git ref, so a trigger can
-            // say "the branch that ships" rather than "every agent's every failure". Absent ⇒ the editor offers
-            // only the channel filter.
+            // A second narrowing axis, for a source whose events carry one (e.g. a pipeline's git ref); absent ⇒ only
+            // the channel filter is offered.
             branchField: TriggerFieldContributionSchema.optional().describe(
                 'A second narrowing axis, for a source whose events carry one: a pipeline\'s git ref, so a trigger can say "the branch that ships" rather than "every agent\'s every failure".',
             ),

package/src/points/viewers.ts

@@ -1,25 +1,21 @@
 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. */
+// A custom file viewer the extension may register at runtime; the host resolves an open file to it by extension,
+// fetches the content, and renders the registered component. The host owns the fetch and open-file lifecycle and the
+// daemon credentials; the extension only renders.
 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.
-     */
+    // What the host hands the extension:
+    // text - decoded utf8, for a format that is text (svg, a subtitle track, a notebook).
+    // blob - the whole file in memory, for a format that must be parsed end to end (a .docx, a spreadsheet). Bounded by
+    // the daemon's raw-read cap.
+    // url - a streaming URL the component points an element at, for anything range-read rather than parsed (audio,
+    // video); the host mints the credential and keeps it out of the extension.
     fetch: z
         .enum(["text", "blob", "url"])
         .describe(

package/src/powers-diff.ts

@@ -1,19 +1,12 @@
 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. */
+// What an update asks for, mechanically. Each manifest folds to a set of POWERS, the consequential facts an owner
+// approved, under a stable key (compared) with a plain sentence (shown). The diff is set arithmetic over the keys.
+// Deliberately excludes plain settings, display marks, category and version; a power's internals moving keeps its key,
+// since the sha pin answers that question instead.
 
 export interface PowersDiff {
-    // Powers the new manifest declares that the installed one didn't, the reason an update re-asks.
+    // 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[];
@@ -80,8 +73,8 @@ const powersOf = (manifest: ExtensionManifest): Map<string, string> => {
     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.
+// `before` absent covers a first install: everything the manifest declares is `added`, the same vocabulary the install
+// dialog already renders.
 export const diffPowers = (before: ExtensionManifest | undefined, after: ExtensionManifest): PowersDiff => {
     const from = before === undefined ? new Map<string, string>() : powersOf(before);
     const to = powersOf(after);