@event4u/agent-config 2.25.0 → 3.0.0

package/dist/server/token.js

@@ -0,0 +1,68 @@
+/**
+ * Per-process bearer token for the local server.
+ *
+ * Council security mandate (security-engineer): 127.0.0.1 bind is
+ * necessary but not sufficient. Any co-resident process or browser
+ * tab can `fetch('http://127.0.0.1:<port>/')`. We require an
+ * `Authorization: Bearer <token>` header on every API request. The
+ * token is fresh per process, written to
+ * `~/.event4u/agent-config/local-server.token` with mode 0600, and
+ * the UI bundle reads it via a `?token=…` query param on the initial
+ * page load (handed back as a cookie by the server's static-file
+ * handler — see `src/server/app.ts`).
+ *
+ * The file is replaced (not appended) on every process boot. A stale
+ * token from a previous process is invalid.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+function tokenDir() {
+    return resolve(homedir(), '.event4u', 'agent-config');
+}
+function tokenPath() {
+    return resolve(tokenDir(), 'local-server.token');
+}
+/**
+ * Generate a fresh token, persist it with mode 0600, return the
+ * token string + on-disk path.
+ */
+export function mintToken() {
+    const token = randomBytes(32).toString('hex');
+    const dir = tokenDir();
+    const path = tokenPath();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+    return { token, path };
+}
+/**
+ * Constant-time compare of two hex-encoded tokens (avoid leaking the
+ * compare length via early-exit timing).
+ */
+export function tokensMatch(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= (a.charCodeAt(i) ^ b.charCodeAt(i));
+    }
+    return diff === 0;
+}
+/**
+ * Default directory used to persist the token. Exported so tests can
+ * stat the file with the expected absolute path.
+ */
+export function defaultTokenPath() {
+    return tokenPath();
+}
+/**
+ * Default token directory (parent of `defaultTokenPath`). Exported
+ * for the same reason as `defaultTokenPath`.
+ */
+export function defaultTokenDir() {
+    const _unused = dirname; // silence unused-import noise; dirname is part of public API contract
+    void _unused;
+    return tokenDir();
+}
+//# sourceMappingURL=token.js.map

package/dist/server/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/server/token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAS7C,SAAS,QAAQ;IACb,OAAO,OAAO,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,SAAS;IACd,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,oBAAoB,CAAC,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACrB,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,SAAS,EAAE,CAAC;IACzB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,aAAa,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC5C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC5B,OAAO,SAAS,EAAE,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,sEAAsE;IAC/F,KAAK,OAAO,CAAC;IACb,OAAO,QAAQ,EAAE,CAAC;AACtB,CAAC"}

package/dist/server/writeRoot.js

@@ -0,0 +1,67 @@
+/**
+ * Write-root resolution.
+ *
+ * Decides where `.agent-settings.yml`, `.agent-user.md`,
+ * `.agent-config/wizard-state.json` and the 2PC intent markers live for
+ * the current server invocation.
+ *
+ *   - Inside the `@event4u/agent-config` package (CWD's `package.json#name`
+ *     matches): `<cwd>/agents/` — package-sandbox mode. Protects the
+ *     maintainer's global config while iterating on the wizard itself.
+ *   - Anywhere else: `~/.event4u/agent-config/` — global mode. The wizard
+ *     produces user-scope state, not project-scope.
+ *
+ * Legacy-read-fallback: in global mode the CWD is also returned as
+ * `legacyReadRoot`. Read paths check `writeRoot` first; on ENOENT they
+ * fall back to `legacyReadRoot` so a project that already has a local
+ * `.agent-settings.yml` from a previous release keeps working. The next
+ * write lands in `writeRoot`, silently migrating the file.
+ */
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+const GLOBAL_REL = join('.event4u', 'agent-config');
+const PACKAGE_SANDBOX_SUBDIR = 'agents';
+const PACKAGE_NAME = '@event4u/agent-config';
+/** True when `cwd/package.json#name === '@event4u/agent-config'`. */
+export function isInsidePackage(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.name === PACKAGE_NAME;
+    }
+    catch {
+        return false;
+    }
+}
+/** Absolute path to the user-scope global config directory. */
+export function globalWriteRoot(home = homedir()) {
+    return join(home, GLOBAL_REL);
+}
+export function resolveWriteRoot(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    if (opts.override !== undefined) {
+        return {
+            writeRoot: resolve(opts.override),
+            legacyReadRoot: null,
+            mode: 'global',
+        };
+    }
+    if (isInsidePackage(cwd)) {
+        return {
+            writeRoot: join(cwd, PACKAGE_SANDBOX_SUBDIR),
+            legacyReadRoot: null,
+            mode: 'package-sandbox',
+        };
+    }
+    const writeRoot = globalWriteRoot(opts.home);
+    const legacyReadRoot = cwd !== writeRoot ? cwd : null;
+    return { writeRoot, legacyReadRoot, mode: 'global' };
+}
+/** Create the write-root directory tree if missing. Mode 0700 for global. */
+export function ensureWriteRoot(writeRoot) {
+    mkdirSync(writeRoot, { recursive: true, mode: 0o700 });
+}
+//# sourceMappingURL=writeRoot.js.map

package/dist/server/writeRoot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeRoot.js","sourceRoot":"","sources":["../../src/server/writeRoot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiB1C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;AACpD,MAAM,sBAAsB,GAAG,QAAQ,CAAC;AACxC,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAE7C,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,GAAW;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC1C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAuB,CAAC;QAC5E,OAAO,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAAC,OAAe,OAAO,EAAE;IACpD,OAAO,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAClC,CAAC;AAcD,MAAM,UAAU,gBAAgB,CAAC,OAAuB,EAAE;IACtD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/C,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO;YACH,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;YACjC,cAAc,EAAE,IAAI;YACpB,IAAI,EAAE,QAAQ;SACjB,CAAC;IACN,CAAC;IACD,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;YACH,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,sBAAsB,CAAC;YAC5C,cAAc,EAAE,IAAI;YACpB,IAAI,EAAE,iBAAiB;SAC1B,CAAC;IACN,CAAC;IACD,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,cAAc,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IACtD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACzD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC7C,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/dist/server/writeRoot.test.js

@@ -0,0 +1,73 @@
+/**
+ * Unit tests for `resolveWriteRoot`.
+ *
+ *   - Inside the package (`package.json#name === '@event4u/agent-config'`)
+ *     resolves to `<cwd>/agents/`, no legacy fallback.
+ *   - Outside the package resolves to `<home>/.event4u/agent-config/`
+ *     and surfaces CWD as `legacyReadRoot`.
+ *   - Explicit `override` short-circuits both branches.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveWriteRoot, isInsidePackage, globalWriteRoot } from './writeRoot.js';
+describe('resolveWriteRoot', () => {
+    let scratch;
+    beforeEach(() => {
+        scratch = mkdtempSync(join(tmpdir(), 'writeroot-'));
+    });
+    afterEach(() => {
+        rmSync(scratch, { recursive: true, force: true });
+    });
+    it('returns package-sandbox mode when CWD is the agent-config package', () => {
+        const repo = join(scratch, 'repo');
+        mkdirSync(repo, { recursive: true });
+        writeFileSync(join(repo, 'package.json'), JSON.stringify({ name: '@event4u/agent-config' }));
+        const res = resolveWriteRoot({ cwd: repo });
+        expect(res.mode).toBe('package-sandbox');
+        expect(res.writeRoot).toBe(join(repo, 'agents'));
+        expect(res.legacyReadRoot).toBeNull();
+    });
+    it('returns global mode with legacy fallback when CWD is a consumer project', () => {
+        const consumer = join(scratch, 'consumer');
+        const home = join(scratch, 'home');
+        mkdirSync(consumer, { recursive: true });
+        mkdirSync(home, { recursive: true });
+        writeFileSync(join(consumer, 'package.json'), JSON.stringify({ name: 'some-app' }));
+        const res = resolveWriteRoot({ cwd: consumer, home });
+        expect(res.mode).toBe('global');
+        expect(res.writeRoot).toBe(join(home, '.event4u', 'agent-config'));
+        expect(res.legacyReadRoot).toBe(consumer);
+    });
+    it('returns global mode with no legacy fallback when CWD has no package.json', () => {
+        const home = join(scratch, 'home');
+        const cwd = join(scratch, 'empty');
+        mkdirSync(home, { recursive: true });
+        mkdirSync(cwd, { recursive: true });
+        const res = resolveWriteRoot({ cwd, home });
+        expect(res.mode).toBe('global');
+        expect(res.writeRoot).toBe(join(home, '.event4u', 'agent-config'));
+        expect(res.legacyReadRoot).toBe(cwd);
+    });
+    it('honours explicit override and suppresses legacy fallback', () => {
+        const cwd = join(scratch, 'consumer');
+        mkdirSync(cwd, { recursive: true });
+        writeFileSync(join(cwd, 'package.json'), JSON.stringify({ name: '@event4u/agent-config' }));
+        const override = join(scratch, 'pinned');
+        const res = resolveWriteRoot({ cwd, override });
+        expect(res.mode).toBe('global');
+        expect(res.writeRoot).toBe(override);
+        expect(res.legacyReadRoot).toBeNull();
+    });
+    it('isInsidePackage detects a malformed package.json gracefully', () => {
+        const cwd = join(scratch, 'broken');
+        mkdirSync(cwd, { recursive: true });
+        writeFileSync(join(cwd, 'package.json'), '{ not json');
+        expect(isInsidePackage(cwd)).toBe(false);
+    });
+    it('globalWriteRoot honours an explicit home', () => {
+        expect(globalWriteRoot('/tmp/some-home')).toBe('/tmp/some-home/.event4u/agent-config');
+    });
+});
+//# sourceMappingURL=writeRoot.test.js.map

package/dist/server/writeRoot.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeRoot.test.js","sourceRoot":"","sources":["../../src/server/writeRoot.test.ts"],"names":[],"mappings":"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"}

package/dist/shared/userMd/formAdapter.js

@@ -0,0 +1,105 @@
+/**
+ * Form adapter for `.agent-user.md`.
+ *
+ * Bridges the raw markdown body (signal in WizardPage / UserMdPanel) and
+ * the structured UserMdForm value. Lives under `src/shared/` so both the
+ * server and the UI can round-trip identically; ESLint enforces no-Node
+ * imports (`./schema.ts` and `./utils.ts` already comply).
+ *
+ * Default frontmatter mirrors `templates/agent-user.md` so a freshly
+ * loaded body without frontmatter still produces a renderable form (every
+ * field has *something*), while keeping `name`, `role[0]`, and
+ * `voice_sample` empty — the wizard surfaces those as 422 issues when
+ * the user tries to finish with them blank.
+ *
+ * Round-trip discipline: `formToBody` always emits block-style YAML via
+ * `composeUserMd`; `bodyToForm` runs `parseUserMd` and merges field-by-
+ * field over `defaultFrontmatter()` so a malformed or partial frontmatter
+ * never crashes the form.
+ */
+import { parseUserMd, composeUserMd } from './utils.js';
+/**
+ * Defaults for a fresh form. Matches `templates/agent-user.md`:
+ * `last_updated` is 1970-01-01 so any user-driven edit visibly bumps it.
+ */
+export function defaultFrontmatter() {
+    return {
+        version: 1,
+        identity: { name: '' },
+        language: 'en',
+        role: [''],
+        style: { formality: 'informal', pace: 'pragmatic' },
+        voice_sample: '',
+        last_updated: '1970-01-01',
+    };
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function pickString(value, fallback) {
+    return typeof value === 'string' ? value : fallback;
+}
+function pickFormality(value) {
+    return value === 'formal' ? 'formal' : 'informal';
+}
+function pickPace(value) {
+    return value === 'thorough' || value === 'rapid' ? value : 'pragmatic';
+}
+function pickRoles(value) {
+    if (!Array.isArray(value))
+        return [''];
+    const filtered = value.filter((v) => typeof v === 'string');
+    return filtered.length === 0 ? [''] : filtered;
+}
+/**
+ * Merge parsed frontmatter over defaults field-by-field. Malformed or
+ * missing entries fall through to the default so the form always has a
+ * complete shape to render — validation runs server-side on save.
+ */
+export function mergeFrontmatter(parsed) {
+    const def = defaultFrontmatter();
+    const identityRaw = isObject(parsed.identity) ? parsed.identity : {};
+    const styleRaw = isObject(parsed.style) ? parsed.style : {};
+    const identity = {
+        name: pickString(identityRaw.name, def.identity.name),
+    };
+    const nickname = identityRaw.nickname;
+    if (typeof nickname === 'string' && nickname !== '')
+        identity.nickname = nickname;
+    return {
+        version: 1,
+        identity,
+        language: pickString(parsed.language, def.language),
+        role: pickRoles(parsed.role),
+        style: {
+            formality: pickFormality(styleRaw.formality),
+            pace: pickPace(styleRaw.pace),
+        },
+        voice_sample: pickString(parsed.voice_sample, def.voice_sample),
+        last_updated: pickString(parsed.last_updated, def.last_updated),
+    };
+}
+/**
+ * Parse a raw `.agent-user.md` body into the structured form value. Empty
+ * or frontmatter-less bodies produce defaults; the markdown content is
+ * preserved verbatim so a manually edited file round-trips cleanly when
+ * the user clicks Save without touching the form.
+ */
+export function bodyToForm(body) {
+    const parsed = parseUserMd(body);
+    return {
+        frontmatter: mergeFrontmatter(parsed.data),
+        content: parsed.content,
+    };
+}
+/**
+ * Compose a structured form value back into a markdown body. The result
+ * always carries block-style frontmatter per the contract.
+ */
+export function formToBody(value) {
+    return composeUserMd({
+        data: value.frontmatter,
+        content: value.content,
+    });
+}
+//# sourceMappingURL=formAdapter.js.map

package/dist/shared/userMd/formAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formAdapter.js","sourceRoot":"","sources":["../../../src/shared/userMd/formAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAQxD;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAC9B,OAAO;QACH,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACtB,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,CAAC,EAAE,CAAC;QACV,KAAK,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE;QACnD,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,YAAY;KAC7B,CAAC;AACN,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IACxB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,QAAgB;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AACxD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACjC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC;AACtD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC5B,OAAO,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC;AAC3E,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IACzE,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA+B;IAC5D,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAC;IACjC,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,MAAM,QAAQ,GAAkC;QAC5C,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;KACxD,CAAC;IACF,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC;IACtC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,EAAE;QAAE,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAClF,OAAO;QACH,OAAO,EAAE,CAAC;QACV,QAAQ;QACR,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC;QACnD,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,KAAK,EAAE;YACH,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC;YAC5C,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;SAChC;QACD,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,YAAY,CAAC;QAC/D,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,YAAY,CAAC;KAClE,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACnC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO;QACH,WAAW,EAAE,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC;QAC1C,OAAO,EAAE,MAAM,CAAC,OAAO;KAC1B,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC7C,OAAO,aAAa,CAAC;QACjB,IAAI,EAAE,KAAK,CAAC,WAAiD;QAC7D,OAAO,EAAE,KAAK,CAAC,OAAO;KACzB,CAAC,CAAC;AACP,CAAC"}

package/dist/shared/userMd/schema.js

@@ -0,0 +1,118 @@
+/**
+ * Zod schema for `.agent-user.md` body.
+ *
+ * Council CRITICAL (2026-05-18): a bare `z.string().max(8000)` is a length
+ * gate, not validation. It accepts malformed frontmatter the agent's identity
+ * parser then refuses to load. The wizard would happily write a file the
+ * agent cannot consume.
+ *
+ * Resolution: validate via the shared `parseUserMd` helper — same
+ * fenced-frontmatter + `js-yaml` parser the agent uses at load time
+ * per ADR-010. The schema runs the parser inside `.superRefine()` and
+ * then validates the parsed frontmatter against the v1 contract
+ * (`docs/contracts/agent-user-schema.md`). Errors surface as Zod
+ * issues with the underlying message; the route returns HTTP 422.
+ *
+ * Strictness (A4 · 2026-05-19): the schema enforces the locked v1
+ * frontmatter — `version`, `identity.name`, `language`, `role[≥1]`,
+ * `style.formality`, `style.pace`, `voice_sample`, `last_updated`. Plain
+ * markdown without frontmatter is rejected; the wizard cannot finish on a
+ * partial body.
+ *
+ * Hard length cap kept at 8 000 chars (form input cap, not security).
+ */
+import { z } from 'zod';
+import { parseUserMd } from './utils.js';
+const MAX_BODY_CHARS = 8_000;
+/**
+ * Seeded role enum mirrors `SEED_PROFILE_IDS` in
+ * `scripts/config/profiles.py`. Per contract, free-form additions are
+ * accepted (forward-compat); closed validation lives in the wizard, not
+ * the loader. The schema therefore validates `role` as `string().min(1)`
+ * — the constant is exported for the wizard UI to use as the seeded
+ * combobox options.
+ */
+export const SEED_ROLE_IDS = [
+    'founder',
+    'developer',
+    'content_creator',
+    'agency',
+    'finance',
+    'ops',
+];
+/** `YYYY-MM-DD` — agent bumps `last_updated` on every accept. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** BCP-47-ish: lowercase primary tag, optional region. "de", "en", "en-US". */
+const LANGUAGE_TAG = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;
+/**
+ * Strict v1 frontmatter shape. Exported for the wizard UI form and for
+ * direct unit tests; the route-level schema (`userMdSchema` below) parses
+ * a body string and feeds the result through this.
+ */
+export const frontmatterSchema = z.object({
+    version: z.literal(1, { errorMap: () => ({ message: 'version must be 1' }) }),
+    identity: z.object({
+        name: z.string().min(1, 'identity.name is required'),
+        nickname: z.string().min(1).optional(),
+    }),
+    language: z
+        .string()
+        .regex(LANGUAGE_TAG, 'language must be a BCP-47 tag (e.g. "de", "en", "en-US")'),
+    role: z
+        .array(z.string().min(1, 'role entries must be non-empty'))
+        .min(1, 'role must list at least one entry'),
+    style: z.object({
+        formality: z.enum(['informal', 'formal'], {
+            errorMap: () => ({ message: 'style.formality must be "informal" or "formal"' }),
+        }),
+        pace: z.enum(['pragmatic', 'thorough', 'rapid'], {
+            errorMap: () => ({ message: 'style.pace must be "pragmatic", "thorough", or "rapid"' }),
+        }),
+    }),
+    voice_sample: z.string().min(1, 'voice_sample is required'),
+    last_updated: z.string().regex(ISO_DATE, 'last_updated must be YYYY-MM-DD'),
+});
+function tryParse(body) {
+    try {
+        const result = parseUserMd(body);
+        // `parseUserMd` returns an empty object when no frontmatter
+        // fence is present; the contract requires v1 frontmatter, so
+        // empty objects fall through to `frontmatterSchema` and fail
+        // there with the missing-required-field issues the wizard
+        // wants to surface.
+        return { ok: true, data: result.data };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'frontmatter parse failed';
+        return { ok: false, message };
+    }
+}
+export const userMdSchema = z.object({
+    body: z
+        .string()
+        .max(MAX_BODY_CHARS, `body must be ≤ ${MAX_BODY_CHARS} chars`)
+        .superRefine((value, ctx) => {
+        const parsed = tryParse(value);
+        if (!parsed.ok) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `.agent-user.md frontmatter invalid: ${parsed.message}`,
+                path: ['body'],
+            });
+            return;
+        }
+        const shape = frontmatterSchema.safeParse(parsed.data);
+        if (shape.success)
+            return;
+        for (const issue of shape.error.issues) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: issue.message,
+                path: ['body', ...issue.path],
+            });
+        }
+    })
+        .describe('Markdown body with v1 frontmatter per agent-user-schema contract.'),
+});
+export const USER_MD_MAX_CHARS = MAX_BODY_CHARS;
+//# sourceMappingURL=schema.js.map

package/dist/shared/userMd/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/shared/userMd/schema.ts"],"names":[],"mappings":"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"}

package/dist/shared/userMd/utils.js

@@ -0,0 +1,74 @@
+/**
+ * Pure parse / compose helpers for `.agent-user.md` bodies.
+ *
+ * Shared between the Fastify server (route validation, wizard finish) and
+ * the Vite-bundled UI (round-trip between structured form and markdown).
+ * Per the council verdict (2026-05-19), this module lives under
+ * `src/shared/` and MUST stay free of Node-only APIs (`fs`, `path`,
+ * `crypto`, `process`, …) — ESLint enforces it.
+ *
+ * Parser choice: a small fenced-frontmatter splitter plus `js-yaml`.
+ * `js-yaml` is pure JS, has no `Buffer` / `process` dependency, and
+ * bundles cleanly into the Vite UI output. (The previous `gray-matter`
+ * implementation crashed in the browser with `ReferenceError: Buffer
+ * is not defined`, which silently broke the wizard's userMd step.)
+ *
+ * Compose choice: `yaml.dump` with `flowLevel: -1` emits **block style**
+ * at every depth. Block-style is required by the schema contract
+ * (`docs/contracts/agent-user-schema.md`): `identity.role` and other
+ * list-valued fields produce clean, line-oriented git diffs that way;
+ * flow style (`role: [a, b]`) is allowed by the parser but rejected
+ * by the contract.
+ */
+import yaml from 'js-yaml';
+/**
+ * Frontmatter fence: leading `---` on its own line, YAML body, trailing
+ * `---` on its own line. Matches `gray-matter`'s default delimiter
+ * behaviour so existing files round-trip identically.
+ */
+const FRONTMATTER_FENCE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+/**
+ * Parse an `.agent-user.md` body into its frontmatter object and the
+ * markdown content that follows.
+ *
+ * Throws on malformed YAML — callers that need a soft failure
+ * (HTTP 422 in routes, form-level error in the UI) should pre-validate
+ * via the Zod schema in `./schema.ts`. A body without a frontmatter
+ * fence parses to `{ data: {}, content: body }`.
+ */
+export function parseUserMd(body) {
+    const match = FRONTMATTER_FENCE.exec(body);
+    if (match === null) {
+        return { data: {}, content: body };
+    }
+    const yamlText = match[1] ?? '';
+    const content = body.slice(match[0].length);
+    const loaded = yaml.load(yamlText);
+    const data = loaded !== null && typeof loaded === 'object' && !Array.isArray(loaded)
+        ? loaded
+        : {};
+    return { data, content };
+}
+/**
+ * Compose a structured `ParsedUserMd` back into an `.agent-user.md`
+ * body, emitting YAML frontmatter in block style (no flow `[a, b]`,
+ * no inline maps) so list-valued fields like `identity.role` produce
+ * one entry per line and diff cleanly in git.
+ *
+ * When `data` is empty, the leading `---\n---\n` fence is omitted.
+ */
+export function composeUserMd(parsed) {
+    if (Object.keys(parsed.data).length === 0) {
+        return parsed.content;
+    }
+    const dumped = yaml.dump(parsed.data, {
+        flowLevel: -1,
+        lineWidth: -1,
+        noRefs: true,
+    });
+    // `yaml.dump` always terminates with `\n`; strip and re-add inside
+    // the fence so the body shape stays `---\n<yaml>\n---\n<content>`.
+    const trimmed = dumped.endsWith('\n') ? dumped.slice(0, -1) : dumped;
+    return `---\n${trimmed}\n---\n${parsed.content}`;
+}
+//# sourceMappingURL=utils.js.map

package/dist/shared/userMd/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/shared/userMd/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,IAAI,MAAM,SAAS,CAAC;AAc3B;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,mCAAmC,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACvC,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,IAAI,GACN,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACnE,CAAC,CAAE,MAAkC;QACrC,CAAC,CAAC,EAAE,CAAC;IACb,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAoB;IAC9C,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,OAAO,MAAM,CAAC,OAAO,CAAC;IAC1B,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;QAClC,SAAS,EAAE,CAAC,CAAC;QACb,SAAS,EAAE,CAAC,CAAC;QACb,MAAM,EAAE,IAAI;KACf,CAAC,CAAC;IACH,mEAAmE;IACnE,mEAAmE;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACrE,OAAO,QAAQ,OAAO,UAAU,MAAM,CAAC,OAAO,EAAE,CAAC;AACrD,CAAC"}