@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/generated-application/surface-outputs.js

@@ -0,0 +1,400 @@
+import { join } from 'node:path';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { parseDocument } from 'yaml';
+import { SURFACE_TARGETS } from '../../surfaces/contract.js';
+import { harnessFact, isGuardSurfaceTarget } from '../../surfaces/harness-registry.js';
+import { RULESYNC_VERSION } from '../../surfaces/generator-adapter.js';
+import { hasTargetMcpServers } from '../../surfaces/mcp.js';
+import { codexWritableRoot, shippedInstructionCapabilities } from '../../surfaces/projection.js';
+import { surfaceModelSha256 } from '../../surfaces/render.js';
+import { GUARD_LOCAL_PATHS } from '../../guards/local-identity.js';
+import { RefusalError, tryParseJson } from '../contract.js';
+import { compareCodeUnits, ownRecord, sha256 } from './shared.js';
+export function expectedSurfaceOutputs(tools, features, sources) {
+    const has = (feature) => features.includes(feature);
+    const hasFor = (target, feature) => has(feature)
+        && harnessFact(target).rulesyncFeatures.some(candidate => candidate === feature);
+    const names = (prefix, suffix) => sources.filter(source => source.path.startsWith(prefix))
+        .map(source => source.path.slice(prefix.length, suffix.length === 0 ? undefined : -suffix.length));
+    const skills = sources.filter(source => source.path.startsWith('skills/')).map(source => source.path.slice('skills/'.length));
+    const permissionRulesForTarget = (target) => {
+        const permissionSource = sources.find(source => source.path === 'permissions.jsonc');
+        if (!permissionSource)
+            return false;
+        const source = ownRecord(JSON.parse(permissionSource.bytes));
+        const sections = [ownRecord(source?.permission), ownRecord(ownRecord(source?.[target])?.permission)];
+        return sections.some(permission => permission !== undefined && Object.values(permission).some(value => {
+            const rules = ownRecord(value);
+            return rules !== undefined && Object.keys(rules).length > 0;
+        }));
+    };
+    const rows = Object.fromEntries(SURFACE_TARGETS.map(target => [target, []]));
+    if (has('rules'))
+        for (const target of SURFACE_TARGETS) {
+            if (!hasFor(target, 'rules'))
+                continue;
+            const root = harnessFact(target).outputs.instruction;
+            if (target === 'cursor')
+                rows[target].push(...names('rules/', '.md').map(name => `${root}/${name}.mdc`));
+            else
+                rows[target].push(root);
+        }
+    if (has('mcp'))
+        for (const target of SURFACE_TARGETS) {
+            if (hasFor(target, 'mcp') && hasTargetMcpServers(sources, target))
+                rows[target].push(harnessFact(target).outputs.mcp);
+        }
+    if (has('hooks'))
+        rows.claudecode.push('.claude/settings.json'), rows.codexcli.push('.codex/hooks.json'), rows.opencode.push('.opencode/plugins/rulesync-hooks.js');
+    if (has('hooks'))
+        rows.cursor.push('.cursor/hooks.json'), rows.grokcli.push('.grok/hooks/rulesync.json');
+    if (has('permissions'))
+        for (const target of SURFACE_TARGETS) {
+            if (!hasFor(target, 'permissions'))
+                continue;
+            if ((target !== 'codexcli' && target !== 'grokcli') || permissionRulesForTarget(target)) {
+                rows[target].push(...harnessFact(target).outputs.permissions);
+            }
+        }
+    if (has('subagents'))
+        for (const name of names('subagents/', '.md')) {
+            rows.claudecode.push(`.claude/agents/${name}.md`);
+            rows.codexcli.push(`.codex/agents/${name}.toml`);
+            rows.opencode.push(`.opencode/agents/${name}.md`);
+            rows.cursor.push(`.cursor/agents/${name}.md`);
+            rows.grokcli.push(`.grok/agents/${name}.md`);
+        }
+    if (has('skills'))
+        for (const path of skills) {
+            rows.claudecode.push(`.claude/skills/${path}`);
+            rows.codexcli.push(`.agents/skills/${path}`);
+            const source = sources.find(candidate => candidate.path === `skills/${path}`);
+            if (path.endsWith('/SKILL.md') && source && expectsCodexSkillSidecar(source.bytes)) {
+                rows.codexcli.push(`.agents/skills/${path.slice(0, -'SKILL.md'.length)}agents/openai.yaml`);
+            }
+            rows.opencode.push(`.opencode/skills/${path}`);
+            rows.cursor.push(`.cursor/skills/${path}`);
+            rows.grokcli.push(`.grok/skills/${path}`);
+        }
+    return Object.fromEntries(tools.map(target => [target, [...new Set(rows[target])].sort(compareCodeUnits)]));
+}
+export function expectedClaudePluginOutputs(features, sources) {
+    const rows = [];
+    if (features.includes('mcp'))
+        rows.push('.mcp.json');
+    if (features.includes('hooks'))
+        rows.push('hooks/hooks.json');
+    if (features.includes('subagents'))
+        for (const source of sources.filter(row => row.path.startsWith('subagents/'))) {
+            rows.push(`agents/${source.path.slice('subagents/'.length)}`);
+        }
+    if (features.includes('skills'))
+        for (const source of sources.filter(row => row.path.startsWith('skills/'))) {
+            rows.push(source.path);
+        }
+    return [...new Set(rows)].sort(compareCodeUnits);
+}
+export function claudePluginManifest() {
+    const bytes = `${JSON.stringify({
+        name: 'cockpit-surfaces',
+        description: 'Generated cockpit agent surfaces.',
+    }, null, 2)}\n`;
+    return { bytes, sha256: sha256(bytes) };
+}
+// A rules overlay is written into the instruction file every harness loads at start, so Rulesync
+// must see it as a root rule. A rule that already says `root: false` (Rulesync's default spelling)
+// is still always loaded; one that narrows itself with `globs` cannot be, so it is refused by name
+// rather than published as a rule that silently applies everywhere.
+export function alwaysLoadedRule(bytes) {
+    if (!bytes.startsWith('---\n'))
+        return { kind: 'complete', bytes: `---\nroot: true\ntargets: ["*"]\n---\n${bytes}` };
+    const end = bytes.indexOf('\n---\n', 4);
+    if (end < 0)
+        return { kind: 'refusal', reason: 'opens a frontmatter block that never closes with a `---` line' };
+    const document = parseDocument(bytes.slice(4, end + 1), { uniqueKeys: true });
+    const frontmatter = document.errors.length === 0 ? document.toJS({ maxAliasCount: 0 }) : undefined;
+    if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+        return { kind: 'refusal', reason: 'has frontmatter that is not a YAML mapping' };
+    }
+    const { globs } = frontmatter;
+    if (globs !== undefined && !(Array.isArray(globs) && globs.every(glob => glob === '**/*' || glob === '**'))) {
+        return { kind: 'refusal', reason: 'limits itself to files with `globs`, but cockpit writes rules overlays into the instruction file every harness loads for every file' };
+    }
+    document.set('root', true);
+    if (!document.has('targets'))
+        document.set('targets', ['*']);
+    return { kind: 'complete', bytes: `---\n${document.toString()}---\n${bytes.slice(end + 5)}` };
+}
+function expectsCodexSkillSidecar(bytes) {
+    if (!bytes.startsWith('---\n'))
+        return false;
+    const end = bytes.indexOf('\n---\n', 4);
+    if (end < 0)
+        return false;
+    let frontmatter;
+    try {
+        const document = parseDocument(bytes.slice(4, end), { uniqueKeys: true });
+        if (document.errors.length > 0)
+            return false;
+        frontmatter = document.toJS({ maxAliasCount: 0 });
+    }
+    catch { /* unparseable input is malformed; the caller refuses it. */
+        return false;
+    }
+    if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter))
+        return false;
+    const codexcli = frontmatter.codexcli;
+    if (!codexcli || typeof codexcli !== 'object' || Array.isArray(codexcli))
+        return false;
+    const metadata = codexcli;
+    const sections = ['interface', 'policy', 'dependencies'].map(key => metadata[key]);
+    const records = sections.filter((section) => section !== null && typeof section === 'object' && !Array.isArray(section));
+    return records.some(section => Object.keys(section).length > 0)
+        || records.length > 0 && typeof metadata['short-description'] === 'string';
+}
+export function emptyGeneration() {
+    return {
+        kind: 'complete', status: 0, diagnostics: [],
+        mechanism: { package: 'rulesync', version: RULESYNC_VERSION, role: 'spelling' },
+        files: [],
+    };
+}
+/**
+ * Claude Code's native Read, Grep and Glob tools never reach the guard hook, so the read denial the
+ * hook applies to shell commands is restated as Claude `Read` deny rules for every declared
+ * instance, mounted or not: an instance is readable by the native tools whether or not a directory
+ * grant names its sibling, and an earlier rule set that followed grants left host-mounted and root
+ * instances readable. Siblings sit outside the project root, where neither `./`, `/..` nor `../`
+ * rules match and an absolute path would differ per clone, so each rule is anchored with `//**` on
+ * the sibling-relative suffix; an instance in the cockpit root itself is anchored at the project
+ * root with `/`. Measured on Claude Code 2.1.314, 2026-10-30, with an unruled control file beside
+ * them: `//**` rules refused Read and Grep of sibling instances and of nested `.secrets` files, and
+ * `/` rules refused root files, while the control stayed readable. Over-matching a deny is safe;
+ * glob metacharacters in a path become `?` so a literal bracket cannot narrow the rule.
+ *
+ * Every `.env` and `.env.*` file is denied too, as the guard denies it. Claude applies a deny before
+ * any allow, so these rules cannot carve out the documentation names the guard exempts: Claude's own
+ * tools refuse `.env.example` and declared templates as well, which a shell `cat` still reads.
+ */
+function claudeReadDenials(siblings, instances) {
+    const literal = (path) => path.replace(/[*?[\]\\!#()]/g, '?');
+    const rules = ['//**/.secrets/**', '//**/.env', '//**/.env.*', ...instanceReadPaths(siblings, instances)
+            .map(row => row.inRoot ? `/${literal(row.path)}` : `//**/${literal(row.path)}`)];
+    return [...new Set(rules)].sort(compareCodeUnits);
+}
+/**
+ * Each declared instance by the path that is the same in every clone: relative to the cockpit root
+ * for an instance there, otherwise the sibling-relative suffix with `..` and `.` segments dropped.
+ */
+function instanceReadPaths(siblings, instances) {
+    return instances.map(instance => {
+        const sibling = siblings.find(row => row.slug === instance.slug);
+        if (!sibling)
+            throw new RefusalError(`declared instance ${instance.path} names sibling ${instance.slug}, whose directory was not authenticated`);
+        if (sibling.path === '')
+            return { inRoot: true, path: instance.path };
+        const suffix = [...sibling.path.split('/'), ...instance.path.split('/')].filter(part => part !== '..' && part !== '.' && part !== '');
+        return { inRoot: false, path: suffix.join('/') };
+    });
+}
+const OPENCODE_CONFIG_SCHEMA = 'https://opencode.ai/config.json';
+/**
+ * OpenCode's native read tool asks its `read` permission with the file path relative to the Git
+ * worktree, and its `*` matches across `/`, so each protected path is denied both as written and
+ * below any prefix: that covers a cockpit root nested in a larger repository and siblings reached
+ * through `../`. Only `*` and `?` are pattern characters there; either one in a path becomes `?`,
+ * which over-matches a deny and so stays safe. The plugin's guard routing refuses the same reads,
+ * case-folded; these rules still deny the declared spellings when the plugin cannot load.
+ */
+export function openCodeReadDenials(siblings, instances) {
+    const literal = (path) => path.replace(/[*?]/g, '?');
+    const paths = ['.secrets/*', ...instanceReadPaths(siblings, instances).map(row => literal(row.path))];
+    return [...new Set(paths.flatMap(path => [path, `*/${path}`]))].sort(compareCodeUnits);
+}
+/** The machine-local file `sync` writes with a sibling's absolute directory, for OpenCode to read. */
+export function openCodeGrantFile(slug) {
+    return `${GUARD_LOCAL_PATHS.directory}/opencode-grant-${slug}`;
+}
+// OpenCode matches `external_directory` patterns against absolute paths and has no token for the
+// project root, so `../api/**` never matches (measured with OpenCode 1.19.4 on 2026-11-02). The
+// committed pattern names a machine-local file instead; OpenCode substitutes `{file:...}` relative
+// to the config file, and refuses to start, naming the file, while it is missing.
+function openCodeExternalDirectories(grants) {
+    return Object.fromEntries([...new Set(grants.filter(grant => grant.target === 'opencode')
+            .map(grant => `{file:${openCodeGrantFile(grant.slug)}}/**`))].sort(compareCodeUnits).map(pattern => [pattern, 'allow']));
+}
+// The cockpit commands the shipped skills tell an agent to run and the guard admits without a
+// prompt. Claude Code allows nothing in its default mode without a rule, so a headless session was
+// denied even `test-run` from its own skill. A rule only lets Claude run the command without asking:
+// the guard hook still runs first, and its ask or deny wins over the rule, so a command whose
+// decider the [work.gates] or [autonomy] policy makes a person still asks. Commands that are always
+// a person's (`init`, `sibling add`) are left out so they keep asking; `down` keeps the data volumes. Measured with Claude Code 2.1.316 on 2026-11-02 beside an unruled control: `Bash(<prefix> *)`
+// ran a matching command headless, the control and a chain with an unmatched part were denied, a hook
+// `ask` denied a matching command, and Claude ignores these rules until a person trusts the workspace.
+const AGENT_COCKPIT_COMMANDS = [
+    'check *', 'confirm *', 'doctor *', 'preflight *', 'logs *', 'ps *', 'restart *', 'rebuild *', 'exec *', 'sync *', 'reset * --apply', 'up *', 'sleep *', 'down *',
+    'runtime measure *', 'test-run *',
+    'work status *', 'work accept *', 'work check *', 'work note *', 'work decide *', 'work answer *', 'work acknowledge *', 'work grade *', 'work signoff *', 'work recover *',
+    'work verify *', 'grade *', 'upgrade *', 'docs check *', 'use *', 'pull *', 'stacks *',
+    'browser drive *', 'browser screenshot *',
+];
+function claudeCommandAllowances() {
+    return Object.fromEntries(['npx --no cockpit', './node_modules/.bin/cockpit']
+        .flatMap(launcher => AGENT_COCKPIT_COMMANDS.map(command => [`${launcher} ${command}`, 'allow'])));
+}
+// What each harness loads at start, from the dated instruction-loading runs. Claude Code applies a
+// scoped rule only to matching files, so a scoped source counts separately there.
+export const GUIDE_LOAD_CHARACTERIZATIONS = Object.freeze(Object.fromEntries(shippedInstructionCapabilities()
+    .filter(fact => isGuardSurfaceTarget(fact.target))
+    .map(fact => [fact.target, {
+        measuredOn: fact.characterizedOn, metric: 'lines', scopeSemantics: fact.target === 'claudecode' ? 'conditional' : 'full',
+        provenance: fact.provenance,
+    }])));
+export function nativeSources(mcp, grants, siblings, instances) {
+    const sources = [];
+    const transports = mcp.result.harnesses.flatMap(row => row.servers);
+    // A remote server no listed tool can carry is left out of the source entirely.
+    const written = mcp.result.servers.flatMap(model => transports.filter(server => server.name === model.name).slice(0, 1));
+    if (written.length > 0) {
+        const native = (server, helperKey) => 'url' in server
+            ? { type: 'http', url: server.url, ...(Object.keys(server.headers).length > 0 ? { headers: server.headers } : {}),
+                ...(server.headersHelper === null ? {} : { [helperKey]: server.headersHelper }), disabled: !server.enabled }
+            : { type: 'stdio', command: server.command, args: server.args, disabled: !server.enabled };
+        const servers = Object.fromEntries(written.map(server => [server.name, native(server, 'headersHelper')]));
+        const targets = Object.fromEntries(mcp.result.harnesses.flatMap(row => {
+            const removed = written.filter(server => !row.servers.some(transport => transport.name === server.name))
+                .map(server => [server.name, null]);
+            // Codex spells Claude Code's headersHelper http_headers_helper; Rulesync passes an unknown
+            // key through to config.toml unchanged.
+            const respelled = row.target === 'codexcli'
+                ? row.servers.filter(server => 'url' in server && server.headersHelper !== null).map(server => [server.name, native(server, 'http_headers_helper')])
+                : [];
+            return removed.length + respelled.length > 0 ? [[harnessFact(row.target).rulesyncTarget, {
+                        mcpServers: Object.fromEntries([...removed, ...respelled]),
+                    }]] : [];
+        }));
+        sources.push({ path: 'mcp.jsonc', bytes: `${JSON.stringify({ mcpServers: servers, ...targets }, null, 2)}\n` });
+    }
+    const paths = (target) => [...new Set(grants.filter(grant => grant.target === target).map(grant => grant.path))].sort(compareCodeUnits);
+    const claudeServers = mcp.result.harnesses.find(row => row.target === 'claudecode')?.servers ?? [];
+    const enabledMcpjsonServers = claudeServers.filter(server => server.enabled).map(server => server.name).sort();
+    // Claude Code ignores `disabled` in `.mcp.json` and offers an unlisted server for one-click
+    // approval; only this list keeps it off (measured with Claude Code 2.1.316 on 2026-11-02).
+    const disabledMcpjsonServers = claudeServers.filter(server => !server.enabled).map(server => server.name).sort();
+    sources.push({ path: 'permissions.jsonc', bytes: `${JSON.stringify({
+            permission: {},
+            claudecode: {
+                permission: {
+                    read: Object.fromEntries(claudeReadDenials(siblings, instances).map(rule => [rule, 'deny'])),
+                    bash: claudeCommandAllowances(),
+                },
+                permissions: { additionalDirectories: paths('claudecode') },
+                enabledMcpjsonServers,
+                ...(disabledMcpjsonServers.length > 0 ? { disabledMcpjsonServers } : {}),
+            },
+            opencode: {
+                permission: { external_directory: openCodeExternalDirectories(grants) },
+            },
+            cursor: {
+                permission: {
+                    read: Object.fromEntries(paths('cursor').map(path => [`${path}/**`, 'allow'])),
+                    write: Object.fromEntries(paths('cursor').map(path => [`${path}/**`, 'allow'])),
+                },
+            },
+            grokcli: {
+                permission: {
+                    read: Object.fromEntries(paths('grokcli').map(path => [`${path}/**`, 'allow'])),
+                    edit: Object.fromEntries(paths('grokcli').map(path => [`${path}/**`, 'allow'])),
+                },
+            },
+        }, null, 2)}\n` });
+    return sources;
+}
+export function nativeFragmentSet(generated, model, paths) {
+    const modelSha256 = surfaceModelSha256(model);
+    if (!modelSha256)
+        return undefined;
+    const fragments = Object.entries(paths).map(([target, path]) => {
+        const row = generated.files.find(candidate => candidate.target === target && candidate.path === path);
+        return row ? { target: target, path, baseSha256: row.sha256, bytes: row.bytes, sha256: row.sha256 } : undefined;
+    });
+    if (fragments.some(fragment => fragment === undefined))
+        return undefined;
+    return { modelSha256, fragments: fragments };
+}
+export function nativeGrantFragmentSet(generated, grants, paths, openCodeReads) {
+    const modelSha256 = surfaceModelSha256(grants);
+    if (!modelSha256)
+        return undefined;
+    const fragments = Object.entries(paths).map(([target, path]) => {
+        const row = generated.files.find(candidate => candidate.target === target && candidate.path === path);
+        if (target !== 'opencode' && target !== 'codexcli') {
+            return row ? { target: target, path, baseSha256: row.sha256, bytes: row.bytes, sha256: row.sha256 } : undefined;
+        }
+        if (target === 'codexcli') {
+            let base = {};
+            if (row) {
+                try {
+                    const parsed = ownRecord(parseToml(row.bytes));
+                    if (!parsed)
+                        return undefined;
+                    base = parsed;
+                }
+                catch { /* unparseable input is malformed; the caller refuses it. */
+                    return undefined;
+                }
+                if (['sandbox_mode', 'sandbox_workspace_write', 'default_permissions', 'permissions']
+                    .some(key => Object.hasOwn(base, key)))
+                    return undefined;
+            }
+            // Codex permission profiles reject the `..` segment required by a portable sibling
+            // grant. Publish the core-owned workspace-write settings alone: mixing the legacy
+            // sandbox with a generated profile would make Codex ignore that profile.
+            // Codex resolves a relative writable root against the directory of the config file,
+            // `.codex/`, not the cockpit root (measured with Codex 0.166.0 on 2026-11-02).
+            const writableRoots = [...new Set(grants.filter(grant => grant.target === target)
+                    .map(grant => codexWritableRoot(grant.path)))].sort(compareCodeUnits);
+            const bytes = stringifyToml({ ...base, sandbox_mode: 'workspace-write', sandbox_workspace_write: { writable_roots: writableRoots } });
+            return { target: target, path, baseSha256: row?.sha256 ?? sha256(''), bytes, sha256: sha256(bytes) };
+        }
+        let base = {};
+        if (row) {
+            const parsed = ownRecord(tryParseJson(row.bytes));
+            if (!parsed)
+                return undefined;
+            base = parsed;
+            if (Object.hasOwn(base, 'permission'))
+                return undefined;
+        }
+        const externalDirectory = openCodeExternalDirectories(grants);
+        const read = Object.fromEntries(openCodeReads.map(rule => [rule, 'deny']));
+        // OpenCode writes `$schema` into a project config that lacks it at every start, which put an
+        // unowned member before the owned region; supplying OpenCode's exact value leaves it untouched.
+        const bytes = `${JSON.stringify({ $schema: OPENCODE_CONFIG_SCHEMA, ...base, permission: { external_directory: externalDirectory, read } }, null, 2)}\n`;
+        return { target: target, path, baseSha256: row?.sha256 ?? sha256(''), bytes, sha256: sha256(bytes) };
+    });
+    if (fragments.some(fragment => fragment === undefined))
+        return undefined;
+    return { modelSha256, fragments: fragments };
+}
+export function bindNativeGrantsToMcp(mcp, grants) {
+    const replacements = new Map();
+    for (const base of mcp.fragments) {
+        const grant = grants.fragments.find(fragment => fragment.target === base.target && fragment.path === base.path);
+        if (!grant)
+            continue;
+        if (grant.baseSha256 !== base.sha256)
+            return undefined;
+        replacements.set(`${base.target}\0${base.path}`, grant);
+    }
+    return { ...mcp, fragments: mcp.fragments.map(fragment => {
+            const grant = replacements.get(`${fragment.target}\0${fragment.path}`);
+            return grant ? { ...fragment, bytes: grant.bytes, sha256: grant.sha256 } : fragment;
+        }) };
+}
+export function nativeMcpPaths(targets) {
+    return Object.fromEntries(targets.map(target => [target, harnessFact(target).outputs.mcp]));
+}
+export function nativeGrantPaths(targets) {
+    return Object.fromEntries(targets.map(target => [target, harnessFact(target).outputs.permissions[0]]));
+}

package/dist/environment/generated-application/surfaces.d.ts

@@ -0,0 +1,3 @@
+import { type OwnershipManifest, type SurfacePriorOwnedEntry } from '../../surfaces/ownership.js';
+import { type GeneratedEnvironmentCommandAdapters, type PreparedEnvironment, type RefusalOutcome } from './shared.js';
+export declare function prepareSurfaces(prepared: PreparedEnvironment, priorOwned: readonly SurfacePriorOwnedEntry[], adapters: GeneratedEnvironmentCommandAdapters, manifest?: OwnershipManifest): Promise<PreparedEnvironment | RefusalOutcome>;