zelari-code 2.54.0 → 2.56.0

package/dist/cli/plugins/bundleDiscover.js

@@ -0,0 +1,74 @@
+/**
+ * plugins/bundleDiscover — find bundle directories under the scan roots.
+ *
+ * Used by `plugin list` and by name-based `plugin enable|disable`.
+ *
+ * The candidate rule is deliberately narrow: a directory is a bundle ONLY when
+ * it carries a manifest. Anything else — a bundle's own `hooks/` / `skills/`
+ * subdirectory, or a different kind of example such as
+ * `examples/extensions/echo-tool` — is not a bundle and must not be reported as
+ * a broken one. A manifest that IS present but invalid still surfaces, as
+ * INVALID: that one the user needs to see.
+ *
+ * @since v2.58.0 (WS6 / plugin bundle v1)
+ */
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { BUNDLE_MANIFEST_FILE } from './bundleManifest.js';
+import { readBundle } from './bundleLoad.js';
+import { isDir, isFile } from './bundleFs.js';
+/**
+ * The roots `plugin list` scans: the repo examples, then the configured paths.
+ *
+ * Deduped (case-insensitively, Windows-safe): `plugin enable` records the
+ * directory CONTAINING a bundle, which is very often the default root itself —
+ * listing the same directory twice in the report would read as a bug.
+ */
+export function defaultBundleRoots(projectRoot, state) {
+    const roots = [path.join(projectRoot, 'examples', 'extensions')];
+    for (const p of state.paths)
+        roots.push(path.resolve(projectRoot, p));
+    const unique = new Map();
+    for (const root of roots)
+        unique.set(path.resolve(root).toLowerCase(), root);
+    return [...unique.values()];
+}
+/** Scan every root for bundle directories and validate each one. Skips dupes. */
+export async function discoverBundles(roots) {
+    const out = [];
+    const seen = new Set();
+    for (const root of roots) {
+        if (!(await isDir(root)))
+            continue;
+        let entries;
+        try {
+            entries = (await readdir(root, { withFileTypes: true }))
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const dir = path.join(root, entry);
+            if (!(await isFile(path.join(dir, BUNDLE_MANIFEST_FILE))))
+                continue;
+            const key = path.resolve(dir);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const result = await readBundle(dir);
+            out.push({
+                dir,
+                name: result.bundle?.name ?? entry,
+                ok: result.bundle !== undefined,
+                errors: result.errors,
+                warnings: result.warnings,
+                ...(result.bundle ? { version: result.bundle.version } : {}),
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=bundleDiscover.js.map

package/dist/cli/plugins/bundleDiscover.js.map

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

package/dist/cli/plugins/bundleFs.js

@@ -0,0 +1,57 @@
+/**
+ * plugins/bundleFs — the filesystem primitives a bundle check needs.
+ *
+ * Extracted so `bundleLoad.ts`, `bundleDiscover.ts` and `bundleCommand.ts`
+ * agree on ONE definition of "the declared file exists and stays inside the
+ * bundle" instead of each growing its own copy.
+ *
+ * @since v2.58.0 (WS6 / plugin bundle v1)
+ */
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+/** `true` only for an existing regular file; never throws. */
+export async function isFile(p) {
+    try {
+        return (await stat(p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** `true` only for an existing directory; never throws. */
+export async function isDir(p) {
+    try {
+        return (await stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Narrow a parsed JSON value to an object literal (not an array, not null). */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Resolve one declared bundle-relative path and prove it is a real file INSIDE
+ * the bundle directory.
+ *
+ * `bundleManifest.ts` already rejects an absolute path or a `..` segment, so
+ * this is defence in depth: a bundle may only ever read files it actually
+ * contains, even if a future path rule loosens. On failure the message names
+ * the manifest, the FIELD and what was wrong; `null` is returned and the
+ * caller skips the entry.
+ */
+export async function resolveInsideBundle(root, relPath, at, manifestPath, errors) {
+    const abs = path.resolve(root, relPath);
+    const rel = path.relative(root, abs);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+        errors.push(`${manifestPath}: invalid bundle manifest at '${at}': path escapes the bundle directory ('${relPath}')`);
+        return null;
+    }
+    if (!(await isFile(abs))) {
+        errors.push(`${manifestPath}: invalid bundle manifest at '${at}': file not found ('${relPath}')`);
+        return null;
+    }
+    return abs;
+}
+//# sourceMappingURL=bundleFs.js.map

package/dist/cli/plugins/bundleFs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundleFs.js","sourceRoot":"","sources":["../../../src/cli/plugins/bundleFs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,CAAS;IACpC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,CAAS;IACnC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAY,EACZ,OAAe,EACf,EAAU,EACV,YAAoB,EACpB,MAAgB;IAEhB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/D,MAAM,CAAC,IAAI,CACT,GAAG,YAAY,iCAAiC,EAAE,0CAA0C,OAAO,IAAI,CACxG,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,iCAAiC,EAAE,uBAAuB,OAAO,IAAI,CAAC,CAAC;QAClG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cli/plugins/bundleHookDef.js

@@ -0,0 +1,70 @@
+import { BUNDLE_HOOK_EVENTS } from './bundleManifest.js';
+import { isRecord } from './bundleFs.js';
+/** Runtime guard for the bundle hook-event vocabulary. */
+export function isBundleHookEvent(value) {
+    return typeof value === 'string' && BUNDLE_HOOK_EVENTS.includes(value);
+}
+/**
+ * Validate `raw` (the hook file's text) as a `HookDefinition` that subscribes
+ * to `event`. Returns either a definition ready for `runner.addHook` or an
+ * error naming the FILE and what is wrong — never both, never a partial one.
+ *
+ * `warnings` collects non-fatal observations (e.g. an event the bundle
+ * vocabulary does not know).
+ */
+export function readHookDefinition(raw, file, event, warnings) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        return { error: `${file}: invalid JSON (${err instanceof Error ? err.message : String(err)})` };
+    }
+    if (!isRecord(json))
+        return { error: `${file}: hook definition must be a JSON object` };
+    const name = json['name'];
+    if (typeof name !== 'string' || name.trim() === '') {
+        return { error: `${file}: hook definition is missing a non-empty "name"` };
+    }
+    const match = json['match'];
+    if (!isRecord(match)) {
+        return { error: `${file}: hook definition is missing a "match" object` };
+    }
+    const events = match['events'];
+    if (!Array.isArray(events) || events.length === 0) {
+        return { error: `${file}: hook "match.events" must be a non-empty array` };
+    }
+    if (!events.includes(event)) {
+        return {
+            error: `${file}: hook does not subscribe to '${event}' (match.events: ${events.join(', ')})`,
+        };
+    }
+    const hasCommand = typeof json['command'] === 'string' && json['command'].trim() !== '';
+    const hasUrl = typeof json['url'] === 'string' && json['url'].trim() !== '';
+    if (hasCommand === hasUrl) {
+        return { error: `${file}: exactly one of "command" or "url" is required` };
+    }
+    for (const extra of events) {
+        if (isBundleHookEvent(extra))
+            continue;
+        warnings.push(`${file}: hook also lists non-bundle event '${String(extra)}' (ignored by the bundle)`);
+    }
+    const tools = match['tools'];
+    const definition = {
+        name,
+        match: {
+            tools: Array.isArray(tools) ? tools.map(String) : ['*'],
+            events: events,
+        },
+    };
+    if (hasCommand)
+        definition.command = json['command'];
+    if (hasUrl)
+        definition.url = json['url'];
+    if (typeof json['timeoutMs'] === 'number')
+        definition.timeoutMs = json['timeoutMs'];
+    if (typeof json['cwd'] === 'string')
+        definition.cwd = json['cwd'];
+    return { definition };
+}
+//# sourceMappingURL=bundleHookDef.js.map

package/dist/cli/plugins/bundleHookDef.js.map

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

package/dist/cli/plugins/bundleLoad.js

@@ -0,0 +1,180 @@
+/**
+ * plugins/bundleLoad — read, validate and LOAD a WS6 plugin bundle.
+ *
+ * Three layers, deliberately separated:
+ *
+ *   1. {@link readBundle}  — I/O + validation. Reads the manifest, then checks
+ *      every DECLARED path: does it exist, does it stay inside the bundle
+ *      directory, and does it parse as the format it claims? Skill files go
+ *      through the REAL loader parser (`skillsMd.parseSkillMd`, the same one
+ *      `/skill` uses), hooks through `bundleHookDef.ts`, and MCP presets through
+ *      the REAL preset registry (`bundleMcp.ts`) — nothing is re-implemented.
+ *   2. {@link projectBundleContributions} — PURE. Given a bundle and the enable
+ *      state it returns the contribution list, and executes NOTHING.
+ *   3. {@link loadBundle} — 1 + 2, the function callers actually want.
+ *
+ * Fail-closed, matching the rest of the CLI: a bundle that is present but not
+ * listed as enabled in `.zelari/plugins.json` contributes NOTHING (not just
+ * "nothing dangerous" — nothing at all). A bundle that fails to read produces
+ * no contributions, never a partial set.
+ *
+ * Module map: manifest schema → `bundleManifest.ts`, FS guards → `bundleFs.ts`,
+ * hook-file validator → `bundleHookDef.ts`, MCP resolution → `bundleMcp.ts`,
+ * discovery → `bundleDiscover.ts`, enable state → `bundleState.ts`, CLI →
+ * `bundleCommand.ts`.
+ *
+ * @since v2.58.0 (WS6 / plugin bundle v1)
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isObserverEvent } from '@zelari/core/harness';
+import { parseSkillMd } from '../skillsMd.js';
+import { BUNDLE_MANIFEST_FILE, parseBundleManifest, } from './bundleManifest.js';
+import { isDir, resolveInsideBundle } from './bundleFs.js';
+import { readHookDefinition } from './bundleHookDef.js';
+import { readMcp } from './bundleMcp.js';
+/** Read the declared skills, each through the real SKILL.md parser. */
+async function readSkills(manifestSkills, root, manifestPath, errors) {
+    const skills = [];
+    for (let i = 0; i < manifestSkills.length; i += 1) {
+        const ref = manifestSkills[i];
+        const abs = await resolveInsideBundle(root, ref.path, `skills.${i}.path`, manifestPath, errors);
+        if (!abs)
+            continue;
+        const skill = parseSkillMd(await readFile(abs, 'utf8'), abs);
+        if (!skill) {
+            errors.push(`${manifestPath}: invalid bundle manifest at 'skills.${i}.path': '${ref.path}' is not a valid SKILL.md ` +
+                '(needs YAML frontmatter with name + description and a non-empty body)');
+            continue;
+        }
+        if (skill.name !== ref.id) {
+            errors.push(`${manifestPath}: invalid bundle manifest at 'skills.${i}.id': id '${ref.id}' ` +
+                `does not match the SKILL.md name '${skill.name}' in '${ref.path}'`);
+            continue;
+        }
+        skills.push({ id: ref.id, path: abs, skill });
+    }
+    return skills;
+}
+/** Read the declared hooks, each validated against the event it claims. */
+async function readHooks(manifestHooks, root, manifestPath, errors, warnings) {
+    const hooks = [];
+    for (let i = 0; i < manifestHooks.length; i += 1) {
+        const ref = manifestHooks[i];
+        const abs = await resolveInsideBundle(root, ref.path, `hooks.${i}.path`, manifestPath, errors);
+        if (!abs)
+            continue;
+        const result = readHookDefinition(await readFile(abs, 'utf8'), abs, ref.event, warnings);
+        if (!result.definition) {
+            errors.push(`${manifestPath}: invalid bundle manifest at 'hooks.${i}.path': ${result.error ?? 'invalid hook'}`);
+            continue;
+        }
+        // `hooks[].config` may only override timeoutMs/cwd — the hook FILE owns
+        // command, url, match and name (see the schema).
+        hooks.push({
+            event: ref.event,
+            path: abs,
+            observer: isObserverEvent(ref.event),
+            definition: { ...result.definition, ...(ref.config ?? {}) },
+        });
+    }
+    return hooks;
+}
+/**
+ * Read + validate one bundle directory. Never throws: every problem is an
+ * entry in `errors` naming the file and the field.
+ */
+export async function readBundle(dir, manifestFileName = BUNDLE_MANIFEST_FILE) {
+    const errors = [];
+    const warnings = [];
+    const root = path.resolve(dir);
+    const manifestPath = path.join(root, manifestFileName);
+    if (!(await isDir(root))) {
+        return { errors: [`${root}: not a bundle directory`], warnings };
+    }
+    let manifestRaw;
+    try {
+        manifestRaw = await readFile(manifestPath, 'utf8');
+    }
+    catch {
+        return { errors: [`${manifestPath}: bundle manifest not found`], warnings };
+    }
+    const parsed = parseBundleManifest(manifestRaw, manifestPath);
+    if (!parsed.manifest)
+        return { errors: parsed.errors, warnings };
+    const manifest = parsed.manifest;
+    const skills = await readSkills(manifest.skills, root, manifestPath, errors);
+    const hooks = await readHooks(manifest.hooks, root, manifestPath, errors, warnings);
+    const mcp = readMcp(manifest.mcp, manifestPath, errors, warnings);
+    const agents = [];
+    for (let i = 0; i < manifest.agents.length; i += 1) {
+        const ref = manifest.agents[i];
+        const at = `agents.${i}.path`;
+        const abs = await resolveInsideBundle(root, ref.path, at, manifestPath, errors);
+        if (!abs)
+            continue;
+        if ((await readFile(abs, 'utf8')).trim() === '') {
+            errors.push(`${manifestPath}: invalid bundle manifest at '${at}': '${ref.path}' is empty`);
+            continue;
+        }
+        agents.push({ id: ref.id, path: abs, ...(ref.description ? { description: ref.description } : {}) });
+    }
+    if (agents.length > 0) {
+        warnings.push('agents are declared and validated but NOT executed (no agent loader in this release)');
+    }
+    if (errors.length > 0)
+        return { errors, warnings };
+    return {
+        bundle: {
+            name: manifest.name,
+            version: manifest.version,
+            ...(manifest.description ? { description: manifest.description } : {}),
+            dir: root,
+            manifestPath,
+            skills,
+            hooks,
+            mcp,
+            agents,
+            warnings,
+        },
+        errors,
+        warnings,
+    };
+}
+/**
+ * PURE projection: bundle + enable state → contribution list. Executes nothing
+ * and reads nothing. A disabled bundle contributes NOTHING (fail-closed), which
+ * is the seam a future apply/eval step consumes.
+ */
+export function projectBundleContributions(bundle, opts) {
+    const base = {
+        bundle: bundle.name,
+        version: bundle.version,
+        dir: bundle.dir,
+        warnings: bundle.warnings,
+    };
+    if (!opts.enabled) {
+        return { ...base, enabled: false, skills: [], hooks: [], mcp: [], agents: [] };
+    }
+    return {
+        ...base,
+        enabled: true,
+        skills: bundle.skills,
+        hooks: bundle.hooks,
+        mcp: bundle.mcp,
+        agents: bundle.agents,
+    };
+}
+/** Read + validate + project. `ok:false` ⇒ no contributions, never partial. */
+export async function loadBundle(dir, opts) {
+    const read = await readBundle(dir);
+    if (!read.bundle)
+        return { ok: false, errors: read.errors, warnings: read.warnings };
+    return {
+        ok: true,
+        errors: [],
+        warnings: read.warnings,
+        contributions: projectBundleContributions(read.bundle, { enabled: opts.enabled }),
+    };
+}
+//# sourceMappingURL=bundleLoad.js.map

package/dist/cli/plugins/bundleLoad.js.map

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

package/dist/cli/plugins/bundleManifest.js

@@ -0,0 +1,233 @@
+/**
+ * plugins/bundleManifest — the WS6 plugin BUNDLE manifest, format v1.
+ *
+ * A *bundle* is a DIRECTORY holding one manifest (`zelari-plugin.json`) plus
+ * the files it declares:
+ *
+ * ```json
+ * {
+ *   "$comment": "optional documentation slot — accepted and stripped",
+ *   "formatVersion": 1,
+ *   "name": "my-bundle",
+ *   "version": "1.0.0",
+ *   "description": "what it gives you",
+ *   "skills": [{ "id": "repo-hygiene", "path": "skills/repo-hygiene/SKILL.md" }],
+ *   "hooks":  [{ "event": "PermissionRequest", "path": "hooks/observer.json" }],
+ *   "mcp":    [{ "name": "my-server", "preset": "unreal-mcp" }],
+ *   "agents": [{ "id": "auditor", "path": "agents/auditor.md" }]
+ * }
+ * ```
+ *
+ * This module is PURE: it parses and validates TEXT. It never touches the
+ * filesystem (does a declared `path` EXIST? — see bundleLoad.ts) and never
+ * executes anything. Every schema is `.strict()`: an unknown key is a
+ * MALFORMED manifest, not a silently ignored option — the `$comment`
+ * documentation slot is the one exception, ACCEPTED AND STRIPPED exactly as in
+ * `safety/permissionPolicy.ts`, so a comment can never change a decision.
+ *
+ * Errors always NAME the file and the offending field
+ * (`<file>: invalid bundle manifest at 'skills.0.path': …`), and ALL problems
+ * are reported — a validator that stops at the first typo turns fixing a
+ * manifest into a guessing game.
+ *
+ * @since v2.58.0 (WS6 / plugin bundle v1)
+ */
+import path from 'node:path';
+import { z } from 'zod';
+/** Manifest file name expected inside a bundle directory. */
+export const BUNDLE_MANIFEST_FILE = 'zelari-plugin.json';
+/** The only format this CLI understands. A future v2 must not load as v1. */
+export const BUNDLE_FORMAT_VERSION = 1;
+/** Slug rule for bundle name / skill id / agent id (mirrors skillsMd.ts). */
+export const BUNDLE_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** MCP server-name rule — mirrors the one `upsertMcpServer` enforces. */
+export const BUNDLE_MCP_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Every event a bundle hook may declare: the four v1.32 GATE events plus the
+ * four v2.57 OBSERVER events (WS5). `satisfies readonly AnyHookEvent[]` makes
+ * the compiler reject a typo or a renamed event here; `OBSERVER_HOOK_EVENTS`
+ * has no runtime counterpart for the gate half, so
+ * `tests/unit/plugin-bundle.test.ts` additionally asserts this list still
+ * contains every event core exports as an observer.
+ */
+export const BUNDLE_HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'SessionStart',
+    'SessionEnd',
+    'PermissionRequest',
+    'SubagentStart',
+    'SubagentEnd',
+    'Notification',
+];
+/**
+ * `$comment` — the ONE non-config key these schemas tolerate. ACCEPTED AND
+ * STRIPPED: never validated, never reaching any consumer, so documentation can
+ * never change behaviour. Every other unknown key stays fatal (same contract
+ * as the WS1 permission policy).
+ */
+const commentSchema = z.string().optional();
+/** Shallow copy of a validated object without its documentation slot. */
+function stripComment(value) {
+    const { $comment: _comment, ...rest } = value;
+    return rest;
+}
+/**
+ * A declared path must stay INSIDE the bundle directory: relative, no drive
+ * letter / root, no `..` segment. `path.win32.isAbsolute` is checked too, so a
+ * `C:\…` path is rejected even when the validator itself runs on POSIX.
+ */
+function escapesBundleRoot(p) {
+    if (path.isAbsolute(p) || path.win32.isAbsolute(p))
+        return true;
+    return p.split(/[\\/]+/).includes('..');
+}
+const bundleRelativePath = z
+    .string()
+    .min(1)
+    .refine((p) => !escapesBundleRoot(p), {
+    message: 'must be a path relative to the bundle directory (no absolute path, no "..")',
+});
+const bundleSlug = (what) => z.string().regex(BUNDLE_SLUG_RE, `${what} must be a slug: lowercase letters, digits, hyphens (max 64)`);
+/** `skills: [{ id, path }]` — one SKILL.md the bundle ships. */
+export const BundleSkillRefSchema = z
+    .object({
+    $comment: commentSchema,
+    id: bundleSlug('skill id'),
+    path: bundleRelativePath,
+})
+    .strict()
+    .transform(stripComment);
+/**
+ * `hooks: [{ event, path, config? }]` — one hook definition FILE plus an
+ * optional overlay.
+ *
+ * `config` may set ONLY `timeoutMs` / `cwd`: the hook file stays authoritative
+ * for `command` / `url` / `match` / `name`, so a manifest can never smuggle an
+ * executable that the hook file does not already declare.
+ */
+export const BundleHookRefSchema = z
+    .object({
+    $comment: commentSchema,
+    event: z.enum(BUNDLE_HOOK_EVENTS, {
+        message: `unknown hook event (expected one of: ${BUNDLE_HOOK_EVENTS.join(', ')})`,
+    }),
+    path: bundleRelativePath,
+    config: z
+        .object({
+        timeoutMs: z.number().int().positive().optional(),
+        cwd: z.string().min(1).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .transform(stripComment);
+/**
+ * `mcp: [{ name, preset | command, args? }]` — exactly ONE of `preset`
+ * (a repo preset id, resolved by `mcp/mcpPresets.ts`) or `command` (a stdio
+ * server) must be given. No `env`: secrets never travel inside a bundle — a
+ * preset factory reads its key from the environment at APPLY time.
+ */
+export const BundleMcpRefSchema = z
+    .object({
+    $comment: commentSchema,
+    name: z
+        .string()
+        .regex(BUNDLE_MCP_NAME_RE, 'mcp name must use letters, digits, underscore or hyphen'),
+    preset: z.string().min(1).optional(),
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).optional(),
+})
+    .strict()
+    .transform(stripComment)
+    .refine((m) => (m.preset === undefined) !== (m.command === undefined), {
+    message: 'exactly one of "preset" (repo preset id) or "command" (stdio server) is required',
+    path: ['preset'],
+});
+/**
+ * `agents: [{ id, path, description? }]` — declared, validated, surfaced as a
+ * contribution, NOT executed: WS6 ships no agent loader (see the debt in
+ * docs/TOOLS.md).
+ */
+export const BundleAgentRefSchema = z
+    .object({
+    $comment: commentSchema,
+    id: bundleSlug('agent id'),
+    path: bundleRelativePath,
+    description: z.string().min(1).optional(),
+})
+    .strict()
+    .transform(stripComment);
+/** The bundle manifest envelope (`.strict()`: unknown key ⇒ malformed). */
+export const BundleManifestSchema = z
+    .object({
+    $comment: commentSchema,
+    formatVersion: z
+        .literal(BUNDLE_FORMAT_VERSION, {
+        message: `unsupported bundle format — this CLI reads formatVersion ${BUNDLE_FORMAT_VERSION}`,
+    })
+        .optional()
+        .default(BUNDLE_FORMAT_VERSION),
+    name: bundleSlug('bundle name'),
+    version: z.string().min(1),
+    description: z.string().min(1).optional(),
+    skills: z.array(BundleSkillRefSchema).default([]),
+    hooks: z.array(BundleHookRefSchema).default([]),
+    mcp: z.array(BundleMcpRefSchema).default([]),
+    agents: z.array(BundleAgentRefSchema).default([]),
+})
+    .strict()
+    .transform(stripComment);
+/** Format every zod issue as `<file>: invalid bundle manifest at '<field>': <why>`. */
+function formatIssues(error, filePath) {
+    return error.issues.map((issue) => {
+        const at = issue.path.length > 0 ? issue.path.join('.') : 'file';
+        return `${filePath}: invalid bundle manifest at '${at}': ${issue.message}`;
+    });
+}
+/**
+ * Cross-field rules zod cannot express per-field: an ambiguous manifest
+ * (two entries fighting for the same id / server name) is REJECTED rather than
+ * silently resolved, so "which one won" can never depend on array order.
+ */
+function duplicateErrors(manifest, filePath) {
+    const errors = [];
+    const check = (values, kind, field) => {
+        const seen = new Set();
+        values.forEach((value, i) => {
+            if (seen.has(value)) {
+                errors.push(`${filePath}: invalid bundle manifest at '${field}.${i}': duplicate ${kind} '${value}'`);
+            }
+            seen.add(value);
+        });
+    };
+    check(manifest.skills.map((s) => s.id), 'skill id', 'skills');
+    check(manifest.mcp.map((m) => m.name), 'mcp server name', 'mcp');
+    check(manifest.agents.map((a) => a.id), 'agent id', 'agents');
+    return errors;
+}
+/**
+ * Parse manifest TEXT (already read from disk). Invalid JSON, a schema
+ * violation, an unknown key (`$comment` aside), a declared path escaping the
+ * bundle root, or a duplicate id all come back as `errors` naming the file and
+ * the field; `manifest` is then absent — never a half-usable manifest.
+ */
+export function parseBundleManifest(raw, filePath) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { errors: [`${filePath}: invalid JSON (${detail})`] };
+    }
+    const parsed = BundleManifestSchema.safeParse(json);
+    if (!parsed.success)
+        return { errors: formatIssues(parsed.error, filePath) };
+    const errors = duplicateErrors(parsed.data, filePath);
+    if (errors.length > 0)
+        return { errors };
+    return { manifest: parsed.data, errors: [] };
+}
+//# sourceMappingURL=bundleManifest.js.map

package/dist/cli/plugins/bundleManifest.js.map

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