@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/setup/command.d.ts

@@ -0,0 +1,4 @@
+import type { SetupCommandAdapters, SetupCommandInput, SetupCommandResult } from '../environment/application/setup.js';
+import type { SetupApplicationOutcome } from '../environment/application/setup.js';
+export type { SetupCommandAdapters, SetupCommandInput, SetupCommandResult };
+export declare function setupCommand(input: SetupCommandInput, adapters: SetupCommandAdapters): Promise<SetupApplicationOutcome>;

package/dist/setup/command.js

@@ -0,0 +1,4 @@
+import { runSetup } from '../environment/application/setup.js';
+export function setupCommand(input, adapters) {
+    return runSetup(input, adapters);
+}

package/dist/sha256.d.ts

@@ -0,0 +1 @@
+export declare function sha256Hex(value: string | Uint8Array): string;

package/dist/sha256.js

@@ -0,0 +1,4 @@
+import { createHash } from 'node:crypto';
+export function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}

package/dist/surfaces/adoption.d.ts

@@ -0,0 +1,41 @@
+import { type AdoptableSurfacePath } from './contract.js';
+export type AdoptionDiagnostic = Readonly<{
+    code: 'SURFACE_ADOPTION_REFUSED';
+    message: string;
+    target: string;
+}>;
+export type AdoptedSettingsInspection = Readonly<{
+    kind: 'complete';
+    value: Record<string, unknown>;
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: AdoptionDiagnostic;
+}>;
+export type AdoptedSurfaceMerge = Readonly<{
+    kind: 'complete';
+    bytes: string;
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: AdoptionDiagnostic;
+}>;
+export declare function adoptedCopyPath(path: AdoptableSurfacePath): string;
+/**
+ * Refuse, by key, everything in an adopted file that could switch off or route around the guard,
+ * or that carries an authority cockpit declares elsewhere. Sources for each key:
+ * - `disableAllHooks`: the guard evaluator names it as the switch that turns Claude's hook off.
+ * - `permissions.defaultMode = "bypassPermissions"`: starts every Claude session with no prompts.
+ * - `hooks.*` naming the guard transport: would re-register or shadow the guard hook (both
+ *   restriction adapters register it as a PreToolUse hook in these files).
+ * - `permissions.additionalDirectories`, `enabledMcpjsonServers`: written from the declared
+ *   directory grants and approved MCP servers.
+ * - `mcp_servers`: written from the approved MCP servers.
+ * - `features.codex_hooks = false`: the generator treats it as Codex's hook feature switch.
+ */
+export declare function inspectAdoptedSettings(path: AdoptableSurfacePath, bytes: string, file?: string): AdoptedSettingsInspection;
+/**
+ * Render one adopted harness settings file: the team's keys plus cockpit's. Hooks follow the same
+ * composition rule as two cockpit producers of one file; Claude permission rules are unioned with
+ * cockpit's deny kept authoritative; any other key is the team's unless cockpit writes it, and then
+ * the two must agree.
+ */
+export declare function mergeAdoptedSurface(path: AdoptableSurfacePath, adoptedBytes: string, cockpitBytes: string | undefined): AdoptedSurfaceMerge;

package/dist/surfaces/adoption.js

@@ -0,0 +1,217 @@
+/**
+ * Owns the merge of a team's adopted harness settings file with cockpit's rendering of the same
+ * path, and the refusals that stop an adopted file from switching off or bypassing the guard.
+ *
+ * It is pure: callers read the adopted copy and supply cockpit's rendered bytes. It does not
+ * decide which files are adopted (cockpit.toml's `[[surfaces.adopted]]` rows do), and it never
+ * writes; the generated application publishes the merged bytes as an ordinary whole-file surface.
+ */
+import { parse as parseToml, stringify as stringifyToml, TomlError } from 'smol-toml';
+import { parseJsonText } from '../environment/contract.js';
+import { ADOPTED_SURFACE_ROOT } from './contract.js';
+import { composeHookSettings } from './render.js';
+// Every guard transport is published below this directory; an adopted hook that names it is
+// re-registering or shadowing the guard rather than adding a team hook.
+const GUARD_DIRECTORY = '.cockpit/guards/';
+export function adoptedCopyPath(path) {
+    return `${ADOPTED_SURFACE_ROOT}/${path}`;
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function refusal(file, key, reason) {
+    return { kind: 'refusal', diagnostic: { code: 'SURFACE_ADOPTION_REFUSED', target: `${file}#${key}`,
+            message: `adopted settings in ${file} set \`${key}\`, which ${reason}; remove \`${key}\` from ${file} and re-run npx --no cockpit sync --config <your cockpit.toml>` } };
+}
+function parse(path, bytes, file) {
+    const invalid = (reason) => ({ kind: 'refusal', diagnostic: { code: 'SURFACE_ADOPTION_REFUSED', target: file,
+            message: `${reason}; fix it and re-run npx --no cockpit sync --config <your cockpit.toml>` } });
+    let value;
+    if (path === '.codex/config.toml') {
+        try {
+            value = parseToml(bytes);
+        }
+        catch (error) {
+            if (!(error instanceof TomlError))
+                throw error;
+            return invalid(`${file} is not valid TOML at line ${error.line}, column ${error.column}`);
+        }
+    }
+    else {
+        const parsed = parseJsonText(bytes, file, 'one settings object');
+        if ('refusal' in parsed)
+            return invalid(parsed.refusal);
+        value = parsed.value;
+    }
+    if (!record(value))
+        return { kind: 'refusal', diagnostic: { code: 'SURFACE_ADOPTION_REFUSED', target: file,
+                message: `${file} must hold one settings object at its root; fix it and re-run npx --no cockpit sync --config <your cockpit.toml>` } };
+    return { kind: 'complete', value };
+}
+function guardHookReference(value, file) {
+    const hooks = value.hooks;
+    if (hooks === undefined)
+        return undefined;
+    if (!record(hooks))
+        return refusal(file, 'hooks', 'must be an object of hook events for cockpit to keep its guard hook beside the team\'s');
+    for (const [event, rows] of Object.entries(hooks)) {
+        if (!Array.isArray(rows))
+            return refusal(file, `hooks.${event}`, 'must be a list of hook entries');
+        if (JSON.stringify(rows).includes(GUARD_DIRECTORY)) {
+            return refusal(file, `hooks.${event}`, 'registers or overrides cockpit\'s guard hook; cockpit adds that hook itself');
+        }
+    }
+    return undefined;
+}
+/**
+ * Refuse, by key, everything in an adopted file that could switch off or route around the guard,
+ * or that carries an authority cockpit declares elsewhere. Sources for each key:
+ * - `disableAllHooks`: the guard evaluator names it as the switch that turns Claude's hook off.
+ * - `permissions.defaultMode = "bypassPermissions"`: starts every Claude session with no prompts.
+ * - `hooks.*` naming the guard transport: would re-register or shadow the guard hook (both
+ *   restriction adapters register it as a PreToolUse hook in these files).
+ * - `permissions.additionalDirectories`, `enabledMcpjsonServers`: written from the declared
+ *   directory grants and approved MCP servers.
+ * - `mcp_servers`: written from the approved MCP servers.
+ * - `features.codex_hooks = false`: the generator treats it as Codex's hook feature switch.
+ */
+export function inspectAdoptedSettings(path, bytes, file = adoptedCopyPath(path)) {
+    const parsed = parse(path, bytes, file);
+    if (parsed.kind !== 'complete')
+        return parsed;
+    const value = parsed.value;
+    if (path === '.claude/settings.json') {
+        if (Object.hasOwn(value, 'disableAllHooks') && value.disableAllHooks !== false) {
+            return refusal(file, 'disableAllHooks', 'switches off every hook, including cockpit\'s guard');
+        }
+        const permissions = value.permissions;
+        if (permissions !== undefined && !record(permissions))
+            return refusal(file, 'permissions', 'must be an object');
+        if (permissions?.defaultMode === 'bypassPermissions') {
+            return refusal(file, 'permissions.defaultMode', 'is "bypassPermissions" and starts every session with no permission prompts');
+        }
+        if (permissions && Object.hasOwn(permissions, 'additionalDirectories')) {
+            return refusal(file, 'permissions.additionalDirectories', 'cockpit writes from the declared sibling directory grants; declare the directory as a sibling instead');
+        }
+        if (Object.hasOwn(value, 'enabledMcpjsonServers')) {
+            return refusal(file, 'enabledMcpjsonServers', 'cockpit writes from the approved MCP servers; approve the server under [mcp] instead');
+        }
+    }
+    if (path === '.codex/config.toml') {
+        if (Object.hasOwn(value, 'mcp_servers')) {
+            return refusal(file, 'mcp_servers', 'cockpit writes from the approved MCP servers; approve the server under [mcp] instead');
+        }
+        const features = value.features;
+        if (record(features) && Object.hasOwn(features, 'codex_hooks') && features.codex_hooks !== true) {
+            return refusal(file, 'features.codex_hooks', 'switches off Codex hooks, including cockpit\'s guard');
+        }
+    }
+    if (path !== '.codex/config.toml') {
+        const hookRefusal = guardHookReference(value, file);
+        if (hookRefusal)
+            return hookRefusal;
+    }
+    return parsed;
+}
+function same(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function owned(file, key) {
+    return refusal(file, key, 'cockpit writes with a different value');
+}
+function strings(value) {
+    return Array.isArray(value) && value.every(item => typeof item === 'string');
+}
+/**
+ * Claude permission rules are unioned. Claude evaluates deny before allow, and the merge keeps that
+ * true in the file as well: a rule cockpit denies never also appears as a team allow or ask.
+ */
+function mergePermissions(cockpit, adopted, file) {
+    const base = cockpit ?? {};
+    const team = adopted ?? {};
+    if (!record(base) || !record(team))
+        return refusal(file, 'permissions', 'must be an object');
+    const result = { ...base };
+    for (const key of ['allow', 'ask', 'deny']) {
+        if (base[key] !== undefined && !strings(base[key]))
+            return refusal(file, `permissions.${key}`, 'cockpit could not read as a list of rules');
+        if (team[key] !== undefined && !strings(team[key]))
+            return refusal(file, `permissions.${key}`, 'must be a list of permission rules');
+    }
+    const denied = new Set(strings(base.deny) ? base.deny : []);
+    for (const key of ['allow', 'ask', 'deny']) {
+        if (base[key] === undefined && team[key] === undefined)
+            continue;
+        const rules = [...new Set([...(base[key] ?? []), ...(team[key] ?? [])])];
+        result[key] = key === 'deny' ? rules : rules.filter(rule => !denied.has(rule));
+    }
+    for (const [key, value] of Object.entries(team)) {
+        if (key === 'allow' || key === 'ask' || key === 'deny')
+            continue;
+        if (Object.hasOwn(result, key) && !same(result[key], value))
+            return owned(file, `permissions.${key}`);
+        result[key] = value;
+    }
+    return { kind: 'complete', value: result };
+}
+/** Tables merge key by key; any value cockpit also writes must match it exactly. */
+function mergeTables(cockpit, adopted, file, prefix = '') {
+    const result = { ...cockpit };
+    for (const [key, value] of Object.entries(adopted)) {
+        const name = prefix === '' ? key : `${prefix}.${key}`;
+        if (!Object.hasOwn(result, key)) {
+            result[key] = value;
+            continue;
+        }
+        const current = result[key];
+        if (record(current) && record(value)) {
+            const merged = mergeTables(current, value, file, name);
+            if (merged.kind !== 'complete')
+                return merged;
+            result[key] = merged.value;
+        }
+        else if (!same(current, value))
+            return owned(file, name);
+    }
+    return { kind: 'complete', value: result };
+}
+/**
+ * Render one adopted harness settings file: the team's keys plus cockpit's. Hooks follow the same
+ * composition rule as two cockpit producers of one file; Claude permission rules are unioned with
+ * cockpit's deny kept authoritative; any other key is the team's unless cockpit writes it, and then
+ * the two must agree.
+ */
+export function mergeAdoptedSurface(path, adoptedBytes, cockpitBytes) {
+    const file = adoptedCopyPath(path);
+    const inspected = inspectAdoptedSettings(path, adoptedBytes, file);
+    if (inspected.kind !== 'complete')
+        return inspected;
+    if (cockpitBytes === undefined)
+        return { kind: 'complete', bytes: adoptedBytes };
+    const rendered = parse(path, cockpitBytes, path);
+    if (rendered.kind !== 'complete')
+        return { kind: 'refusal', diagnostic: { code: 'SURFACE_ADOPTION_REFUSED', target: path,
+                message: `cockpit's rendering of ${path} could not be read for merging` } };
+    const adopted = inspected.value;
+    const cockpit = rendered.value;
+    if (path === '.codex/config.toml') {
+        const merged = mergeTables(cockpit, adopted, file);
+        return merged.kind === 'complete' ? { kind: 'complete', bytes: stringifyToml(merged.value) } : merged;
+    }
+    let base = cockpit;
+    let team = adopted;
+    if (path === '.claude/settings.json') {
+        const permissions = mergePermissions(cockpit.permissions, adopted.permissions, file);
+        if (permissions.kind !== 'complete')
+            return permissions;
+        const { permissions: _teamPermissions, ...rest } = adopted;
+        base = { ...cockpit, permissions: permissions.value };
+        team = rest;
+    }
+    const composed = composeHookSettings([base, team]);
+    if (composed.kind !== 'complete')
+        return composed.reason === 'divergent' ? owned(file, composed.key)
+            : refusal(file, composed.key, 'is not shaped as a hook registration');
+    return { kind: 'complete', bytes: `${JSON.stringify(composed.value, null, 2)}\n` };
+}

package/dist/surfaces/consumer-instructions.d.ts

@@ -0,0 +1,20 @@
+export interface ConsumerInstructionsInput {
+    readonly name: string;
+    readonly configFile: string;
+    readonly siblings: readonly Readonly<{
+        dir: string;
+        purpose: string;
+        acquire: 'auto' | 'manual' | 'none';
+    }>[];
+    readonly hasStack: boolean;
+    readonly guards: Readonly<{
+        declaredDatabaseHosts: readonly string[];
+        declaredVendorHosts: readonly string[];
+        pushRefusedBranches: readonly string[];
+    }>;
+    readonly skills: readonly Readonly<{
+        name: string;
+        description: string | undefined;
+    }>[];
+}
+export declare function renderConsumerInstructions(input: ConsumerInstructionsInput): string;

package/dist/surfaces/consumer-instructions.js

@@ -0,0 +1,43 @@
+// Owns: the opening section of the AGENTS.md / CLAUDE.md that `cockpit sync` writes into a
+// consumer's cockpit: what the cockpit is, how to work in it, the rules and their reasons, and
+// which skills exist. Must not: read files, invent values the configuration does not declare, or
+// restate what a skill already says (it points at the skill instead).
+// Hands off to: generated-application/, which supplies the facts, and render.ts, which places
+// the text in the shared instruction region beside the testing-tier guide.
+//
+// Why it is short: this text loads into every agent session, and adherence falls as it grows.
+// Every command is spelled through cockpitCommand so an agent can run it exactly as written.
+import { cockpitCommand } from '../fix-catalogue.js';
+const HOSTS_SHOWN = 5;
+const inline = (value) => value.replace(/\s+/g, ' ').replaceAll('`', "'").trim();
+const cell = (value) => inline(value).replaceAll('|', '\\|');
+const code = (value) => `\`${inline(value)}\``;
+function hosts(label, declared) {
+    if (declared.length === 0)
+        return `${label}: not declared`;
+    const shown = declared.slice(0, HOSTS_SHOWN).map(code).join(', ');
+    return `${label}: ${shown}${declared.length > HOSTS_SHOWN ? ` and ${declared.length - HOSTS_SHOWN} more in \`[guards]\`` : ''}`;
+}
+export function renderConsumerInstructions(input) {
+    const run = (command, args) => code(cockpitCommand(command, { config: input.configFile, ...(args === undefined ? {} : { args }) }));
+    const acquire = { auto: `${run('setup')} clones it`, manual: 'a person clones it', none: 'already on disk' };
+    const { declaredDatabaseHosts, declaredVendorHosts, pushRefusedBranches } = input.guards;
+    const noHosts = declaredDatabaseHosts.length + declaredVendorHosts.length === 0;
+    const lines = [
+        '# What this is', '',
+        `This is the ${code(input.name)} cockpit. It gives every agent the same instructions, skills and guards for the repositories below${input.hasStack ? ', and starts them against your working copies' : ''}.`,
+        '',
+        '| Directory | Purpose | How it reaches disk |', '| --- | --- | --- |',
+        ...input.siblings.map(row => `| ${code(row.dir)} | ${cell(row.purpose)} | ${row.acquire}: ${acquire[row.acquire]} |`),
+        '',
+        '# How to work here', '',
+    ];
+    if (input.hasStack)
+        lines.push(`- Run ${run('session', '-- <command>')} to start the stack, run the command against it and release the stack, so nothing is left holding ports; the command gets each leased port under its \`[ports.bases]\` name and each URL as \`COCKPIT_ENTRYPOINT_<NAME>\`. ${run('up')} and ${run('down')} do it by hand (down deletes containers); ${run('doctor')} explains a stack that will not start.`);
+    lines.push(`- Every cockpit command takes \`--config ${inline(input.configFile)}\`. After editing that file, run ${run('sync', '--dry-run')} to preview the generated files, ${run('sync')} to write them and ${run('check')} to confirm nothing drifted. Generated files are committed and compared byte for byte, so an unsynced edit fails review.`, '', '# Rules and why', '');
+    lines.push(`- Never touch a non-local environment. The guard denies commands that reach a declared non-local host (${hosts('database hosts', declaredDatabaseHosts)}; ${hosts('vendor endpoints', declaredVendorHosts)}). A local mistake is cheap; a production one is not.${noHosts ? ' With none declared the guard cannot recognise one, so ask before running anything that might reach a hosted service.' : ''}`);
+    if (pushRefusedBranches.length > 0)
+        lines.push(`- Do not push to ${pushRefusedBranches.map(code).join(' or ')}. The guard refuses it, because those branches are shared and a bad push reaches everyone.`);
+    lines.push(`- Do not hand-edit generated files; edit ${code(input.configFile)} and sync. ${run('check')} reports a hand edit as drift and sync refuses to overwrite it; to recover, undo the edit (or delete a file cockpit wrote whole), then sync.`, '', '# Skills', '', ...input.skills.map(skill => `- ${code(skill.name)}: ${skill.description ? inline(skill.description) : 'not declared'}`));
+    return lines.join('\n') + '\n';
+}

package/dist/surfaces/contract.d.ts

@@ -0,0 +1,42 @@
+import { type SurfaceTarget } from './harness-registry.js';
+export { SURFACE_TARGETS, type SurfaceTarget } from './harness-registry.js';
+export declare const SURFACE_FEATURES: readonly ["rules", "mcp", "subagents", "skills", "hooks", "permissions"];
+export declare const SURFACE_BUNDLE_FORMATS: readonly ["claudecode-plugin"];
+export declare const SURFACE_FILE_MAX_BYTES = 65536;
+export declare const ADOPTABLE_SURFACE_PATHS: readonly [".claude/settings.json", ".codex/config.toml", ".codex/hooks.json"];
+export type AdoptableSurfacePath = typeof ADOPTABLE_SURFACE_PATHS[number];
+export declare const ADOPTED_SURFACE_ROOT = "cockpit/adopted";
+export declare const SURFACE_OUTPUT_MAX_BYTES = 4194304;
+export declare const SURFACE_OUTPUT_MAX_FILES = 256;
+export type SurfaceFeature = typeof SURFACE_FEATURES[number];
+export type SurfaceBundleFormat = typeof SURFACE_BUNDLE_FORMATS[number];
+export interface SurfaceSourceFile {
+    readonly path: string;
+    readonly bytes: string;
+}
+export interface SurfaceBatch {
+    readonly targets: readonly SurfaceTarget[];
+    readonly features: readonly SurfaceFeature[];
+    readonly sources: readonly SurfaceSourceFile[];
+    readonly expectedOutputs: Readonly<Partial<Record<SurfaceTarget, readonly string[]>>>;
+}
+export interface SurfaceBundleBatch {
+    readonly format: SurfaceBundleFormat;
+    readonly features: readonly SurfaceFeature[];
+    readonly sources: readonly SurfaceSourceFile[];
+    readonly expectedOutputs: readonly string[];
+}
+export interface RenderedSurfaceFile {
+    readonly target: SurfaceTarget;
+    readonly path: string;
+    readonly bytes: string;
+    readonly sha256: string;
+}
+/** Whether a path segment names a directory no surface may read or write through. */
+export declare function reservedPathSegment(segment: string): boolean;
+/** A bounded relative POSIX path with no empty, dot, parent or reserved segment. */
+export declare function safeSurfacePath(value: unknown): value is string;
+export declare function surfaceSourcesMatchFeature(input: unknown, feature: SurfaceFeature): boolean;
+export declare function captureSurfaceBatch(input: unknown): SurfaceBatch | undefined;
+export declare function captureSurfaceBundleBatch(input: unknown): SurfaceBundleBatch | undefined;
+export declare function bundleSurfaceFiles(input: readonly RenderedSurfaceFile[]): readonly SurfaceSourceFile[] | undefined;

package/dist/surfaces/contract.js

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto';
+import { snapshotGeneratedJson, snapshotJson } from '../environment/contract.js';
+import { SURFACE_TARGETS } from './harness-registry.js';
+import { exactKeys } from '../exact-keys.js';
+export { SURFACE_TARGETS } from './harness-registry.js';
+export const SURFACE_FEATURES = Object.freeze(['rules', 'mcp', 'subagents', 'skills', 'hooks', 'permissions']);
+export const SURFACE_BUNDLE_FORMATS = Object.freeze(['claudecode-plugin']);
+export const SURFACE_FILE_MAX_BYTES = 65_536;
+// The harness settings files cockpit renders whole and a team may already keep its own copy of.
+// Adoption moves the team's bytes under ADOPTED_SURFACE_ROOT and renders a merge of both; every
+// other surface path is either cockpit's alone or already shares a marked region.
+export const ADOPTABLE_SURFACE_PATHS = Object.freeze(['.claude/settings.json', '.codex/config.toml', '.codex/hooks.json']);
+export const ADOPTED_SURFACE_ROOT = 'cockpit/adopted';
+export const SURFACE_OUTPUT_MAX_BYTES = 4_194_304;
+export const SURFACE_OUTPUT_MAX_FILES = 256;
+const TARGETS = new Set(SURFACE_TARGETS);
+const FEATURES = new Set(SURFACE_FEATURES);
+const CLAUDE_PLUGIN_FEATURES = new Set(['mcp', 'subagents', 'skills', 'hooks']);
+const SHA256 = /^[a-f0-9]{64}$/;
+const RULE_PATH = /^rules\/[^/]+\.md$/;
+const SUBAGENT_PATH = /^subagents\/[^/]+\.md$/;
+const SKILL_PATH = /^skills\/([a-z0-9][a-z0-9-]*)\/(.+)$/;
+// A generated file under Git's directory could install a hook; one under node_modules would be
+// shadowed or wiped by the next install. Folded because the default macOS and Windows filesystems
+// resolve `.GIT` and `Node_Modules` to the same directories. Upper-casing also folds characters
+// such as `ſ`, which lower-casing leaves alone but case-insensitive filesystems treat as `s`.
+const RESERVED_SEGMENTS = new Set(['.GIT', 'NODE_MODULES']);
+/** Whether a path segment names a directory no surface may read or write through. */
+export function reservedPathSegment(segment) {
+    return RESERVED_SEGMENTS.has(segment.normalize('NFC').toUpperCase());
+}
+/** A bounded relative POSIX path with no empty, dot, parent or reserved segment. */
+export function safeSurfacePath(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 4096 && !value.startsWith('/')
+        && !/^[a-z]:[/\\]/i.test(value) && !/[\\\x00-\x1f\x7f]/.test(value)
+        && value.split('/').every(part => part !== '' && part !== '.' && part !== '..' && !reservedPathSegment(part));
+}
+function isObject(value) {
+    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every(item => typeof item === 'string')
+        ? value
+        : undefined;
+}
+function uniqueValues(values) {
+    return new Set(values).size === values.length;
+}
+function sourceFeature(path) {
+    if (RULE_PATH.test(path))
+        return 'rules';
+    if (path === 'mcp.jsonc')
+        return 'mcp';
+    if (SUBAGENT_PATH.test(path))
+        return 'subagents';
+    if (SKILL_PATH.test(path))
+        return 'skills';
+    if (path === 'hooks.jsonc')
+        return 'hooks';
+    if (path === 'permissions.jsonc')
+        return 'permissions';
+    return undefined;
+}
+function validSourceFiles(value, requested) {
+    if (!Array.isArray(value) || value.length === 0)
+        return false;
+    const paths = new Set();
+    const supplied = new Set();
+    const skillRoots = new Set();
+    const skillDefinitions = new Set();
+    for (const item of value) {
+        if (!isObject(item) || !exactKeys(item, ['path', 'bytes'])
+            || typeof item.path !== 'string' || typeof item.bytes !== 'string'
+            || Buffer.byteLength(item.bytes) > SURFACE_FILE_MAX_BYTES
+            || !safeSurfacePath(item.path) || paths.has(item.path))
+            return false;
+        const feature = sourceFeature(item.path);
+        if (!feature || !requested.has(feature))
+            return false;
+        paths.add(item.path);
+        supplied.add(feature);
+        const skill = SKILL_PATH.exec(item.path);
+        if (skill) {
+            const root = skill[1];
+            skillRoots.add(root);
+            if (skill[2] === 'SKILL.md')
+                skillDefinitions.add(root);
+        }
+    }
+    return [...requested].every(feature => supplied.has(feature))
+        && [...skillRoots].every(root => skillDefinitions.has(root));
+}
+export function surfaceSourcesMatchFeature(input, feature) {
+    return FEATURES.has(feature) && validSourceFiles(snapshotJson(input), new Set([feature]));
+}
+function validExpectedOutputs(value, targets) {
+    if (!isObject(value) || !exactKeys(value, targets))
+        return false;
+    for (const target of targets) {
+        const paths = stringArray(value[target]);
+        if (!paths || !uniqueValues(paths) || paths.some(path => !safeSurfacePath(path)))
+            return false;
+    }
+    return true;
+}
+export function captureSurfaceBatch(input) {
+    const snapshot = snapshotJson(input);
+    if (!isObject(snapshot) || !exactKeys(snapshot, ['targets', 'features', 'sources', 'expectedOutputs']))
+        return undefined;
+    const targets = stringArray(snapshot.targets);
+    const features = stringArray(snapshot.features);
+    if (!targets || !uniqueValues(targets) || !targets.every(target => TARGETS.has(target))
+        || !features || !uniqueValues(features) || !features.every(feature => FEATURES.has(feature)))
+        return undefined;
+    const admittedTargets = targets;
+    const admittedFeatures = features;
+    if (!validSourceFiles(snapshot.sources, new Set(admittedFeatures))
+        || !validExpectedOutputs(snapshot.expectedOutputs, admittedTargets))
+        return undefined;
+    return snapshot;
+}
+export function captureSurfaceBundleBatch(input) {
+    const snapshot = snapshotJson(input);
+    if (!isObject(snapshot) || !exactKeys(snapshot, ['format', 'features', 'sources', 'expectedOutputs'])
+        || snapshot.format !== 'claudecode-plugin')
+        return undefined;
+    const features = stringArray(snapshot.features);
+    const expectedOutputs = stringArray(snapshot.expectedOutputs);
+    if (!features || !uniqueValues(features)
+        || !features.every(feature => CLAUDE_PLUGIN_FEATURES.has(feature))
+        || !expectedOutputs || !uniqueValues(expectedOutputs) || expectedOutputs.some(path => !safeSurfacePath(path))
+        || !validSourceFiles(snapshot.sources, new Set(features)))
+        return undefined;
+    return snapshot;
+}
+function renderedFile(value) {
+    if (!isObject(value) || !exactKeys(value, ['target', 'path', 'bytes', 'sha256'])
+        || typeof value.target !== 'string' || !TARGETS.has(value.target)
+        || typeof value.path !== 'string' || !safeSurfacePath(value.path)
+        || typeof value.bytes !== 'string' || Buffer.byteLength(value.bytes) > SURFACE_FILE_MAX_BYTES
+        || typeof value.sha256 !== 'string' || !SHA256.test(value.sha256)
+        || createHash('sha256').update(value.bytes).digest('hex') !== value.sha256)
+        return undefined;
+    return value;
+}
+export function bundleSurfaceFiles(input) {
+    const snapshot = snapshotGeneratedJson(input);
+    if (!Array.isArray(snapshot) || snapshot.length === 0 || snapshot.length > SURFACE_OUTPUT_MAX_FILES)
+        return undefined;
+    const paths = new Set();
+    const bundled = [];
+    let totalBytes = 0;
+    for (const item of snapshot) {
+        const admitted = renderedFile(item);
+        if (!admitted)
+            return undefined;
+        const path = `${admitted.target}/${admitted.path}`;
+        if (paths.has(path))
+            return undefined;
+        totalBytes += Buffer.byteLength(admitted.bytes);
+        if (totalBytes > SURFACE_OUTPUT_MAX_BYTES)
+            return undefined;
+        paths.add(path);
+        bundled.push({ path, bytes: admitted.bytes });
+    }
+    bundled.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    const bounded = snapshotGeneratedJson(bundled);
+    return Array.isArray(bounded) ? bounded : undefined;
+}

package/dist/surfaces/core-declarations.d.ts

@@ -0,0 +1,24 @@
+import type { SurfaceDeclaration } from '../schema.js';
+import type { SurfaceTarget } from './contract.js';
+export declare const CORE_EVALUATOR_ASSET: 'agents/evaluator.agent.md';
+export declare const CORE_SKILL_PROCEDURES: Readonly<{
+    readonly 'cockpit-setup': 'procedures/setup.md';
+    readonly 'cockpit-explain': 'procedures/explain.md';
+    readonly 'cockpit-fix': 'procedures/fix.md';
+    readonly 'cockpit-work': 'procedures/work.md';
+}>;
+export declare const CORE_PROCEDURE_ASSETS: readonly ["skills/procedures/setup.md", "skills/procedures/explain.md", "skills/procedures/fix.md", "skills/procedures/work.md"];
+export declare const CORE_SKILL_ASSETS: readonly ["skills/collection.json", "skills/cockpit-setup.skill.md", "skills/cockpit-explain.skill.md", "skills/cockpit-fix.skill.md", "skills/cockpit-work.skill.md", "skills/procedures/setup.md", "skills/procedures/explain.md", "skills/procedures/fix.md", "skills/procedures/work.md"];
+type CoreAsset = Readonly<{
+    bytes: string;
+}>;
+/** Each shipped skill's entry point and its own procedure, as neutral skill sources. */
+export declare function shippedSkillSources(assets: ReadonlyMap<string, CoreAsset>, tools: readonly SurfaceTarget[]): readonly Readonly<{
+    name: string;
+    sources: readonly Readonly<{
+        path: string;
+        bytes: string;
+    }>[];
+}>[] | undefined;
+export declare function coreSurfaceDeclarations(assets: ReadonlyMap<string, CoreAsset>, tools: readonly SurfaceTarget[]): readonly SurfaceDeclaration[] | undefined;
+export {};