@openchamber/sdk 2.5.0 → 2.5.1

package/dist/manifest.js

@@ -87,11 +87,37 @@ export const resolveIntegrationApi = (integration) => {
 };
 /**
  * Host roles a service can stand in for. `browser` answers the agent's
- * `browser.*` actions in place of the in-app browser view; the contract is in
- * `service-providers.ts`. A service that provides a role needs no panel or
- * background entry: the host starts it on the first action.
+ * `browser.*` actions in place of the in-app browser view. `source-control`
+ * makes the extension a Git host next to GitHub, GitLab and Gitea, described
+ * by `contributes.sourceControl`. Both contracts are in `service-providers.ts`.
+ * A service that provides a role needs no panel or background entry: the host
+ * starts it on the first call.
  */
-export const GUEST_SERVICE_PROVIDES = ['browser'];
+export const GUEST_SERVICE_PROVIDES = ['browser', 'source-control'];
+/**
+ * The host names an extension's Git host `ext-<panel.id>`, and provider ids
+ * are at most 32 characters, so a guest taking the role has an id of at most
+ * this many.
+ */
+export const SOURCE_CONTROL_GUEST_ID_MAX = 28;
+/** The provider id OpenChamber gives the Git host an extension provides. */
+export const sourceControlProviderIdOf = (guestId) => `ext-${guestId}`;
+/** Default instances a Git host extension may name. */
+export const SOURCE_CONTROL_DEFAULT_INSTANCES_MAX = 4;
+/** URL templates per kind (`presentation.urls.changeRequest` / `.issue`). */
+export const SOURCE_CONTROL_URL_TEMPLATES_MAX = 8;
+/** Characters in one URL template. */
+export const SOURCE_CONTROL_URL_TEMPLATE_MAX = 256;
+/**
+ * The placeholders a URL template may use, each a whole path segment.
+ * `{namespace+}` is one or more segments (GitLab groups); `{owner}` exactly one.
+ */
+export const SOURCE_CONTROL_URL_TOKENS = ['{owner}', '{namespace+}', '{repo}', '{number}'];
+export const toPublicSourceControl = (contribution) => ({
+    label: contribution.label,
+    defaultInstances: [...contribution.instances.defaultInstances],
+    custom: contribution.instances.custom,
+});
 export const serviceProvides = (service, role) => Boolean(service?.provides?.includes(role));
 /**
  * What a guest may do beyond drawing its own panel. The user approves the

package/dist/parse.d.ts

@@ -114,6 +114,7 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             }>>>;
             provides: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 browser: "browser";
+                "source-control": "source-control";
             }>>>;
             surface: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strip>>;
@@ -170,6 +171,115 @@ export declare const openChamberManifestSchema: z.ZodObject<{
                 text: "text";
             }>>;
         }, z.core.$strip>>>;
+        sourceControl: z.ZodOptional<z.ZodObject<{
+            wire: z.ZodLiteral<1>;
+            label: z.ZodString;
+            terminology: z.ZodObject<{
+                changeRequest: z.ZodEnum<{
+                    change: "change";
+                    mergeRequest: "mergeRequest";
+                    pullRequest: "pullRequest";
+                }>;
+                ci: z.ZodEnum<{
+                    checks: "checks";
+                    pipeline: "pipeline";
+                }>;
+            }, z.core.$strict>;
+            referencePrefix: z.ZodObject<{
+                changeRequest: z.ZodString;
+                issue: z.ZodString;
+            }, z.core.$strict>;
+            repositoryPath: z.ZodEnum<{
+                "namespace/name": "namespace/name";
+                "owner/name": "owner/name";
+            }>;
+            instances: z.ZodObject<{
+                defaultInstances: z.ZodArray<z.ZodString>;
+                custom: z.ZodBoolean;
+                allowLoopbackHttp: z.ZodBoolean;
+                allowPort: z.ZodBoolean;
+                placeholder: z.ZodString;
+            }, z.core.$strict>;
+            capabilities: z.ZodObject<{
+                projects: z.ZodDefault<z.ZodBoolean>;
+                issues: z.ZodDefault<z.ZodBoolean>;
+                changeRequests: z.ZodDefault<z.ZodBoolean>;
+                draftChangeRequests: z.ZodDefault<z.ZodBoolean>;
+                merge: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+                    methods: z.ZodArray<z.ZodEnum<{
+                        merge: "merge";
+                        rebase: "rebase";
+                        squash: "squash";
+                        submit: "submit";
+                    }>>;
+                }, z.core.$strict>]>>;
+                ci: z.ZodDefault<z.ZodBoolean>;
+                comments: z.ZodDefault<z.ZodBoolean>;
+                reviews: z.ZodDefault<z.ZodBoolean>;
+                state: z.ZodDefault<z.ZodBoolean>;
+                labels: z.ZodDefault<z.ZodBoolean>;
+                reviewers: z.ZodDefault<z.ZodBoolean>;
+                changeRequestPatch: z.ZodDefault<z.ZodBoolean>;
+                liveSummaries: z.ZodDefault<z.ZodBoolean>;
+                reviewModel: z.ZodOptional<z.ZodEnum<{
+                    verdict: "verdict";
+                    votes: "votes";
+                }>>;
+                revisions: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>;
+            token: z.ZodObject<{
+                header: z.ZodEnum<{
+                    authorization: "authorization";
+                    "private-token": "private-token";
+                }>;
+                scheme: z.ZodEnum<{
+                    basic: "basic";
+                    bearer: "bearer";
+                    none: "none";
+                    token: "token";
+                }>;
+                username: z.ZodOptional<z.ZodBoolean>;
+                scopes: z.ZodArray<z.ZodString>;
+                createPath: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            transport: z.ZodObject<{
+                httpsUsername: z.ZodUnion<readonly [z.ZodObject<{
+                    kind: z.ZodLiteral<"login">;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"fixed">;
+                    value: z.ZodString;
+                }, z.core.$strict>]>;
+                appendDotGitToHttpsClone: z.ZodBoolean;
+            }, z.core.$strict>;
+            limits: z.ZodObject<{
+                commentMaxLength: z.ZodNumber;
+                reviewerId: z.ZodEnum<{
+                    login: "login";
+                    numeric: "numeric";
+                }>;
+                labelsMax: z.ZodNumber;
+                reviewersMax: z.ZodNumber;
+            }, z.core.$strict>;
+            trackedItems: z.ZodObject<{
+                batchLimit: z.ZodNumber;
+            }, z.core.$strict>;
+            presentation: z.ZodObject<{
+                abbreviation: z.ZodString;
+                promptNoun: z.ZodString;
+                sharedNumberSpace: z.ZodBoolean;
+                iconPath: z.ZodOptional<z.ZodString>;
+                urls: z.ZodObject<{
+                    changeRequest: z.ZodArray<z.ZodString>;
+                    issue: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>;
+                features: z.ZodObject<{
+                    authorCanReview: z.ZodDefault<z.ZodBoolean>;
+                    issueCloseReason: z.ZodDefault<z.ZodBoolean>;
+                    submitRequirements: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>;
+                changeRequestTemplates: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const PACKAGE_VERSION_PATTERN: RegExp;
@@ -289,6 +399,7 @@ export declare const packageManifestSchema: z.ZodObject<{
                 }>>>;
                 provides: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                     browser: "browser";
+                    "source-control": "source-control";
                 }>>>;
                 surface: z.ZodOptional<z.ZodLiteral<true>>;
             }, z.core.$strip>>;
@@ -345,6 +456,115 @@ export declare const packageManifestSchema: z.ZodObject<{
                     text: "text";
                 }>>;
             }, z.core.$strip>>>;
+            sourceControl: z.ZodOptional<z.ZodObject<{
+                wire: z.ZodLiteral<1>;
+                label: z.ZodString;
+                terminology: z.ZodObject<{
+                    changeRequest: z.ZodEnum<{
+                        change: "change";
+                        mergeRequest: "mergeRequest";
+                        pullRequest: "pullRequest";
+                    }>;
+                    ci: z.ZodEnum<{
+                        checks: "checks";
+                        pipeline: "pipeline";
+                    }>;
+                }, z.core.$strict>;
+                referencePrefix: z.ZodObject<{
+                    changeRequest: z.ZodString;
+                    issue: z.ZodString;
+                }, z.core.$strict>;
+                repositoryPath: z.ZodEnum<{
+                    "namespace/name": "namespace/name";
+                    "owner/name": "owner/name";
+                }>;
+                instances: z.ZodObject<{
+                    defaultInstances: z.ZodArray<z.ZodString>;
+                    custom: z.ZodBoolean;
+                    allowLoopbackHttp: z.ZodBoolean;
+                    allowPort: z.ZodBoolean;
+                    placeholder: z.ZodString;
+                }, z.core.$strict>;
+                capabilities: z.ZodObject<{
+                    projects: z.ZodDefault<z.ZodBoolean>;
+                    issues: z.ZodDefault<z.ZodBoolean>;
+                    changeRequests: z.ZodDefault<z.ZodBoolean>;
+                    draftChangeRequests: z.ZodDefault<z.ZodBoolean>;
+                    merge: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+                        methods: z.ZodArray<z.ZodEnum<{
+                            merge: "merge";
+                            rebase: "rebase";
+                            squash: "squash";
+                            submit: "submit";
+                        }>>;
+                    }, z.core.$strict>]>>;
+                    ci: z.ZodDefault<z.ZodBoolean>;
+                    comments: z.ZodDefault<z.ZodBoolean>;
+                    reviews: z.ZodDefault<z.ZodBoolean>;
+                    state: z.ZodDefault<z.ZodBoolean>;
+                    labels: z.ZodDefault<z.ZodBoolean>;
+                    reviewers: z.ZodDefault<z.ZodBoolean>;
+                    changeRequestPatch: z.ZodDefault<z.ZodBoolean>;
+                    liveSummaries: z.ZodDefault<z.ZodBoolean>;
+                    reviewModel: z.ZodOptional<z.ZodEnum<{
+                        verdict: "verdict";
+                        votes: "votes";
+                    }>>;
+                    revisions: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>;
+                token: z.ZodObject<{
+                    header: z.ZodEnum<{
+                        authorization: "authorization";
+                        "private-token": "private-token";
+                    }>;
+                    scheme: z.ZodEnum<{
+                        basic: "basic";
+                        bearer: "bearer";
+                        none: "none";
+                        token: "token";
+                    }>;
+                    username: z.ZodOptional<z.ZodBoolean>;
+                    scopes: z.ZodArray<z.ZodString>;
+                    createPath: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+                transport: z.ZodObject<{
+                    httpsUsername: z.ZodUnion<readonly [z.ZodObject<{
+                        kind: z.ZodLiteral<"login">;
+                    }, z.core.$strict>, z.ZodObject<{
+                        kind: z.ZodLiteral<"fixed">;
+                        value: z.ZodString;
+                    }, z.core.$strict>]>;
+                    appendDotGitToHttpsClone: z.ZodBoolean;
+                }, z.core.$strict>;
+                limits: z.ZodObject<{
+                    commentMaxLength: z.ZodNumber;
+                    reviewerId: z.ZodEnum<{
+                        login: "login";
+                        numeric: "numeric";
+                    }>;
+                    labelsMax: z.ZodNumber;
+                    reviewersMax: z.ZodNumber;
+                }, z.core.$strict>;
+                trackedItems: z.ZodObject<{
+                    batchLimit: z.ZodNumber;
+                }, z.core.$strict>;
+                presentation: z.ZodObject<{
+                    abbreviation: z.ZodString;
+                    promptNoun: z.ZodString;
+                    sharedNumberSpace: z.ZodBoolean;
+                    iconPath: z.ZodOptional<z.ZodString>;
+                    urls: z.ZodObject<{
+                        changeRequest: z.ZodArray<z.ZodString>;
+                        issue: z.ZodArray<z.ZodString>;
+                    }, z.core.$strict>;
+                    features: z.ZodObject<{
+                        authorCanReview: z.ZodDefault<z.ZodBoolean>;
+                        issueCloseReason: z.ZodDefault<z.ZodBoolean>;
+                        submitRequirements: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strict>;
+                    changeRequestTemplates: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>;
+            }, z.core.$strict>>;
         }, z.core.$strip>;
     }, z.core.$strip>;
 }, z.core.$strip>;

package/dist/parse.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { OPENCHAMBER_SDK_MANIFEST_API_VERSIONS } from './api-version.js';
 import { OPENCHAMBER_ENGINE_PATTERN } from './host-version.js';
-import { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_FILESYSTEM_PATTERNS_MAX, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_ORIGINS_MAX, GUEST_SERVICE_PROVIDES, GUEST_TOOLS_MAX, GUEST_TOOL_COLUMNS_MAX, GUEST_TOOL_COLUMN_MAX, GUEST_TOOL_LANGUAGE_MAX, GUEST_TOOL_MATCH, GUEST_TOOL_MATCH_MAX, GUEST_TOOL_NAME_MAX, GUEST_TOOL_OUTPUTS, GUEST_TOOL_TEMPLATE_MAX, PANEL_ID, hasGuestPage, isGuestFilesystemPattern, isGuestPackageSvgIcon, isSafeAssetPath, resolveIntegrationAuth, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, } from './manifest.js';
+import { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_FILESYSTEM_PATTERNS_MAX, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_ORIGINS_MAX, GUEST_SERVICE_PROVIDES, GUEST_TOOLS_MAX, GUEST_TOOL_COLUMNS_MAX, GUEST_TOOL_COLUMN_MAX, GUEST_TOOL_LANGUAGE_MAX, GUEST_TOOL_MATCH, GUEST_TOOL_MATCH_MAX, GUEST_TOOL_NAME_MAX, GUEST_TOOL_OUTPUTS, GUEST_TOOL_TEMPLATE_MAX, PANEL_ID, hasGuestPage, isGuestFilesystemPattern, isGuestPackageSvgIcon, isSafeAssetPath, resolveIntegrationAuth, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, SOURCE_CONTROL_DEFAULT_INSTANCES_MAX, SOURCE_CONTROL_GUEST_ID_MAX, SOURCE_CONTROL_URL_TEMPLATES_MAX, SOURCE_CONTROL_URL_TEMPLATE_MAX, SOURCE_CONTROL_URL_TOKENS, } from './manifest.js';
 import { GUEST_FILE_EDITORS_MAX, GUEST_FILE_EDITOR_PATTERNS_MAX, GUEST_FILE_EDITOR_TITLE_MAX, isFileEditorPattern, } from './file-editor.js';
 const isPanelIcon = (value) => (PANEL_ID.test(value) || isGuestPackageSvgIcon(value));
 const isHttpsUrl = (value) => {
@@ -156,6 +156,148 @@ const serviceSchema = z.object({
         .optional(),
     surface: z.literal(true).optional(),
 });
+// SVG path data only, the same rule the UI applies to a provider's icon path:
+// commands, numbers and separators, nothing that could close the attribute.
+const SVG_PATH_DATA = /^[MmLlHhVvCcSsQqTtAaZz0-9eE.,\s+-]+$/;
+// A literal URL template segment: no placeholder braces, no regex syntax.
+const URL_TEMPLATE_LITERAL = /^[A-Za-z0-9._~-]+$/;
+const URL_TEMPLATE_TOKENS = new Set(SOURCE_CONTROL_URL_TOKENS);
+/**
+ * A web path template of a change request or issue: `/`, then segments that
+ * are each a literal or one of the known placeholders. `{repo}` and
+ * `{number}` appear exactly once, and the repository's owner exactly once as
+ * `{owner}` (`owner/name` paths) or `{namespace+}` (`namespace/name` paths).
+ */
+const isUrlTemplate = (value, repositoryPath) => {
+    if (!value.startsWith('/') || value.length > SOURCE_CONTROL_URL_TEMPLATE_MAX)
+        return false;
+    const segments = value.slice(1).split('/');
+    // A normalized URL never has a `.` or `..` segment, so a template with one matches nothing.
+    if (segments.some((segment) => segment === '.' || segment === '..'))
+        return false;
+    if (segments.some((segment) => !URL_TEMPLATE_TOKENS.has(segment) && !URL_TEMPLATE_LITERAL.test(segment)))
+        return false;
+    const count = (token) => segments.filter((segment) => segment === token).length;
+    const owner = repositoryPath === 'owner/name' ? '{owner}' : '{namespace+}';
+    const other = repositoryPath === 'owner/name' ? '{namespace+}' : '{owner}';
+    return count('{repo}') === 1 && count('{number}') === 1 && count(owner) === 1 && count(other) === 0;
+};
+// A file inside the repository, as a change request template names it:
+// relative, no `.` or `..` segment, dot-folders like `.gitea/` allowed.
+const REPOSITORY_FILE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+const isRepositoryFilePath = (value) => value.length > 0 && value.split('/')
+    .every((segment) => REPOSITORY_FILE_SEGMENT.test(segment) && segment !== '.' && segment !== '..');
+const prefixSchema = z.string().min(1).max(4).regex(/^\S+$/);
+const literalSchema = z.string().trim().min(1).max(64);
+const sourceControlCapabilitiesSchema = z.object({
+    projects: z.boolean().default(false),
+    issues: z.boolean().default(false),
+    changeRequests: z.boolean().default(false),
+    draftChangeRequests: z.boolean().default(false),
+    merge: z.union([
+        z.literal(false),
+        z.object({
+            methods: z.array(z.enum(['merge', 'squash', 'rebase', 'submit'])).min(1).max(3)
+                .refine((methods) => new Set(methods).size === methods.length, { message: 'merge methods must be unique' })
+                // A host that submits a change merges it the one way its project is set up.
+                .refine((methods) => !methods.includes('submit') || methods.length === 1, { message: '"submit" is the only merge method when present' }),
+        }).strict(),
+    ]).default(false),
+    ci: z.boolean().default(false),
+    comments: z.boolean().default(false),
+    reviews: z.boolean().default(false),
+    state: z.boolean().default(false),
+    labels: z.boolean().default(false),
+    reviewers: z.boolean().default(false),
+    changeRequestPatch: z.boolean().default(false),
+    liveSummaries: z.boolean().default(false),
+    // Left out rather than defaulted, so a manifest that does not use them parses as before.
+    reviewModel: z.enum(['verdict', 'votes']).optional(),
+    revisions: z.boolean().optional(),
+}).strict();
+// A Git username OpenChamber puts before the token in an HTTPS credential.
+const FIXED_USERNAME = /^[A-Za-z0-9._-]{1,64}$/;
+const urlTemplatesSchema = z.array(z.string().trim().min(1)).max(SOURCE_CONTROL_URL_TEMPLATES_MAX);
+const sourceControlSchema = z.object({
+    wire: z.literal(1),
+    label: literalSchema,
+    terminology: z.object({
+        changeRequest: z.enum(['pullRequest', 'mergeRequest', 'change']),
+        ci: z.enum(['checks', 'pipeline']),
+    }).strict(),
+    referencePrefix: z.object({ changeRequest: prefixSchema, issue: prefixSchema }).strict(),
+    repositoryPath: z.enum(['owner/name', 'namespace/name']),
+    instances: z.object({
+        defaultInstances: z.array(z.string().trim().refine(isHttpsOrigin, { message: 'must be an https origin with no path, like https://git.example.com' }))
+            .max(SOURCE_CONTROL_DEFAULT_INSTANCES_MAX)
+            .refine((origins) => new Set(origins).size === origins.length, { message: 'default instances must be unique' }),
+        custom: z.boolean(),
+        allowLoopbackHttp: z.boolean(),
+        allowPort: z.boolean(),
+        placeholder: z.string().trim().max(256),
+    }).strict().refine((instances) => instances.custom || instances.defaultInstances.length > 0, { message: 'without custom instances, defaultInstances names at least one' }),
+    capabilities: sourceControlCapabilitiesSchema,
+    token: z.object({
+        header: z.enum(['authorization', 'private-token']),
+        scheme: z.enum(['bearer', 'token', 'basic', 'none']),
+        username: z.boolean().optional(),
+        scopes: z.array(z.string().trim().min(1).max(64)).max(32),
+        createPath: z.string().trim().max(256).refine(isSafeApiPath, { message: 'must be a path on the instance starting with "/", with no "." or ".." segment' }).optional(),
+    }).strict().refine((token) => (token.header === 'private-token') === (token.scheme === 'none'), { message: 'private-token takes the bare token; authorization takes a bearer, token or basic scheme' }).refine(
+    // Basic sends `login:token`, so Settings must ask for the login; no other scheme uses one.
+    (token) => (token.scheme === 'basic') === (token.username === true), { message: 'the basic scheme needs username: true, and username is only for the basic scheme' }),
+    transport: z.object({
+        httpsUsername: z.union([
+            z.object({ kind: z.literal('login') }).strict(),
+            z.object({ kind: z.literal('fixed'), value: z.string().regex(FIXED_USERNAME) }).strict(),
+        ]),
+        appendDotGitToHttpsClone: z.boolean(),
+    }).strict(),
+    limits: z.object({
+        commentMaxLength: z.number().int().min(1).max(1_000_000),
+        reviewerId: z.enum(['numeric', 'login']),
+        labelsMax: z.number().int().min(0).max(100),
+        reviewersMax: z.number().int().min(0).max(50),
+    }).strict(),
+    trackedItems: z.object({ batchLimit: z.number().int().min(1).max(50) }).strict(),
+    presentation: z.object({
+        abbreviation: z.string().trim().min(1).max(8),
+        promptNoun: literalSchema,
+        sharedNumberSpace: z.boolean(),
+        iconPath: z.string().max(8192).regex(SVG_PATH_DATA).optional(),
+        urls: z.object({ changeRequest: urlTemplatesSchema, issue: urlTemplatesSchema }).strict(),
+        features: z.object({
+            authorCanReview: z.boolean().default(false),
+            issueCloseReason: z.boolean().default(false),
+            submitRequirements: z.boolean().optional(),
+        }).strict(),
+        changeRequestTemplates: z.array(z.string().trim().max(256).refine(isRepositoryFilePath, {
+            message: 'must be a file path inside the repository, like .gitea/pull_request_template.md, with no "." or ".." segment',
+        })).max(8),
+    }).strict(),
+}).strict().superRefine((value, ctx) => {
+    for (const kind of ['changeRequest', 'issue']) {
+        value.presentation.urls[kind].forEach((template, index) => {
+            if (isUrlTemplate(template, value.repositoryPath))
+                return;
+            ctx.addIssue({
+                code: 'custom', path: ['presentation', 'urls', kind, index],
+                message: `templates start with "/" and use literal segments and ${SOURCE_CONTROL_URL_TOKENS.join(', ')}: {repo} and {number} once, and ${value.repositoryPath === 'owner/name' ? '{owner}' : '{namespace+}'} once for ${value.repositoryPath} paths.`,
+            });
+        });
+    }
+    // Change request patterns are matched first, so an issue template that is
+    // also a change request template would read every issue link as one.
+    const changeRequestTemplates = new Set(value.presentation.urls.changeRequest);
+    value.presentation.urls.issue.forEach((template, index) => {
+        if (!changeRequestTemplates.has(template))
+            return;
+        ctx.addIssue({
+            code: 'custom', path: ['presentation', 'urls', 'issue', index],
+            message: 'is also a changeRequest template; a link names either a change request or an issue.',
+        });
+    });
+});
 const uniqueBy = (items, key) => (new Set(items.map(key)).size === items.length);
 // `roles` only means something on a message action and `payload` only on a
 // session action; a dead field is a misconfiguration and fails closed.
@@ -229,6 +371,7 @@ const contributesSchema = z.object({
     commands: commandsSchema.optional(),
     tools: toolsSchema.optional(),
     fileEditors: fileEditorsSchema.optional(),
+    sourceControl: sourceControlSchema.optional(),
 });
 /**
  * Contributions that need either the panel or background execution frame.
@@ -264,6 +407,23 @@ export const openChamberManifestSchema = z.object({
         openchamber: z.string().trim().regex(OPENCHAMBER_ENGINE_PATTERN),
     }).strict().optional(),
     contributes: contributesSchema.superRefine((contributes, ctx) => {
+        // The Git host and the role that serves it come together, and the host
+        // names it `ext-<panel.id>` within the 32-character provider id.
+        const providesSourceControl = contributes.service?.provides?.includes('source-control') === true;
+        if (providesSourceControl !== (contributes.sourceControl !== undefined)) {
+            ctx.addIssue({
+                code: 'custom', path: ['service', 'provides'],
+                message: 'service.provides "source-control" and contributes.sourceControl come together: declare both or neither.',
+            });
+            return;
+        }
+        if (providesSourceControl && contributes.panel.id.length > SOURCE_CONTROL_GUEST_ID_MAX) {
+            ctx.addIssue({
+                code: 'custom', path: ['service', 'provides'],
+                message: `A source-control extension's panel.id is at most ${SOURCE_CONTROL_GUEST_ID_MAX} characters: OpenChamber names its Git host "ext-<panel.id>".`,
+            });
+            return;
+        }
         // Docking only means something for a page beside a shared surface.
         const docked = contributes.panel.dock !== undefined || contributes.panel.size !== undefined;
         if (docked && !(contributes.service?.surface && hasGuestPage(contributes))) {
@@ -343,6 +503,9 @@ const fail = (code, message) => ({
     code,
     message,
 });
+/** `contributes.sourceControl.instances.defaultInstances[0]`, relative to the `openchamber` block. */
+const fieldPath = (issuePath) => (issuePath[0] === 'openchamber' ? issuePath.slice(1) : issuePath)
+    .reduce((field, segment) => (Number.isInteger(segment) ? `${field}[${String(segment)}]` : `${field ? `${field}.` : ''}${String(segment)}`), '');
 const failureFromIssue = (issue) => {
     // Paths are reported relative to the `openchamber` block whether the
     // document was a bare manifest or a package.json envelope.
@@ -427,8 +590,17 @@ const failureFromIssue = (issue) => {
     if (path.startsWith('contributes.integration')) {
         return fail('invalid-integration', 'contributes.integration needs a name, description, and oauth, token, or host.');
     }
+    if (path.startsWith('contributes.sourceControl')) {
+        // The field is named either way: a refine's message alone does not say which entry failed.
+        const field = fieldPath(issue.path);
+        return fail('invalid-service', issue.code === 'custom'
+            ? `${field}: ${issue.message}`
+            : `${field} is invalid: see "contributes.sourceControl" in GUEST_SERVICES.md for every field.`);
+    }
     if (path.startsWith('contributes.service')) {
-        return fail('invalid-service', 'contributes.service needs entry, runtime "host", optional permissions, optional provides ("browser"), and optional surface (true).');
+        return fail('invalid-service', issue.code === 'custom'
+            ? issue.message
+            : 'contributes.service needs entry, runtime "host", optional permissions, optional provides ("browser", "source-control"), and optional surface (true).');
     }
     return fail('missing-panel', 'contributes.panel is required.');
 };

package/dist/schemas.d.ts

@@ -4,6 +4,6 @@ export { guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceSnap
 export { guestStatusControlsSchema, guestStatusControlEventSchema } from './status-control-schemas.ts';
 export { guestPopoverClosedEventSchema, guestPopoverRequestSchema } from './popover-schemas.ts';
 export { guestMessageSchema, hostMessageSchema, parseGuestMessage, parseHostMessage, } from './protocol.ts';
-export { browserControlActionSchema, browserProviderResultSchema } from './service-provider-schemas.ts';
+export { browserControlActionSchema, browserProviderResultSchema, sourceControlProviderMethodSchema, sourceControlProviderSchemasV1, } from './service-provider-schemas.ts';
 export { surfaceClipboardAnswerSchema, surfaceControllerSchema, surfaceHostMessageSchema, surfaceInputEventSchema, surfaceResizeAnswerSchema, surfaceViewerMessageSchema, } from './service-surface-schemas.ts';
 export type { SurfaceHostMessage, SurfaceViewerMessage } from './service-surface-schemas.ts';

package/dist/schemas.js

@@ -6,5 +6,5 @@ export { guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceSnap
 export { guestStatusControlsSchema, guestStatusControlEventSchema } from './status-control-schemas.js';
 export { guestPopoverClosedEventSchema, guestPopoverRequestSchema } from './popover-schemas.js';
 export { guestMessageSchema, hostMessageSchema, parseGuestMessage, parseHostMessage, } from './protocol.js';
-export { browserControlActionSchema, browserProviderResultSchema } from './service-provider-schemas.js';
+export { browserControlActionSchema, browserProviderResultSchema, sourceControlProviderMethodSchema, sourceControlProviderSchemasV1, } from './service-provider-schemas.js';
 export { surfaceClipboardAnswerSchema, surfaceControllerSchema, surfaceHostMessageSchema, surfaceInputEventSchema, surfaceResizeAnswerSchema, surfaceViewerMessageSchema, } from './service-surface-schemas.js';