@shrkcrft/plugin-api 0.1.0-alpha.2

package/dist/pack-manifest.d.ts.map

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

package/dist/pack-manifest.js

@@ -0,0 +1,96 @@
+/**
+ * SharkCraft pack manifest.
+ *
+ * A "pack" is a third-party npm package that ships SharkCraft assets —
+ * knowledge entries, rules, paths, templates, pipelines, MCP-tool registrations,
+ * AI-provider adapters, etc.
+ *
+ * The pack itself is just an npm package whose `package.json` declares a
+ * `sharkcraft.manifest` entry pointing at a TS/JS file that default-exports an
+ * `ISharkCraftPackManifest`. The discovery scanner (planned for v0.2) finds
+ * these manifests in `node_modules/` and registers their contributions.
+ *
+ * Today this file declares the types and a small validator. The discovery
+ * runner is intentionally out of scope for v0.1 — see docs/packs.md.
+ */
+/**
+ * Lightweight runtime validation of a pack manifest. We do not use zod here
+ * because plugin-api should remain dependency-light; consumers can layer zod
+ * on top if they want.
+ */
+export function validatePackManifest(value) {
+    const issues = [];
+    if (!value || typeof value !== 'object') {
+        return { valid: false, issues: [{ field: '<root>', message: 'manifest must be an object' }] };
+    }
+    const obj = value;
+    if (obj.schema !== 'sharkcraft.pack/v1') {
+        issues.push({ field: 'schema', message: 'schema must be "sharkcraft.pack/v1"' });
+    }
+    const info = obj.info;
+    if (!info || typeof info !== 'object') {
+        issues.push({ field: 'info', message: 'info is required' });
+    }
+    else {
+        if (typeof info.name !== 'string' || info.name.length === 0) {
+            issues.push({ field: 'info.name', message: 'info.name must be a non-empty string' });
+        }
+        if (typeof info.version !== 'string' || info.version.length === 0) {
+            issues.push({ field: 'info.version', message: 'info.version must be a non-empty string' });
+        }
+    }
+    const contributions = obj.contributions;
+    if (!contributions || typeof contributions !== 'object') {
+        issues.push({ field: 'contributions', message: 'contributions is required' });
+    }
+    else {
+        for (const key of [
+            'knowledgeFiles',
+            'ruleFiles',
+            'pathFiles',
+            'templateFiles',
+            'pipelineFiles',
+            'docsFiles',
+            'presetFiles',
+            'boundaryFiles',
+            'contextTestFiles',
+            'agentTestFiles',
+            'mcpToolFiles',
+            'aiProviderFiles',
+            'scaffoldPatternFiles',
+            'policyCheckFiles',
+            'constructFiles',
+            'constructFacetFiles',
+            'playbookFiles',
+            'searchTuningFiles',
+            'feedbackRuleFiles',
+            'decisionFiles',
+            'pathConventionFiles',
+            'pluginLifecycleProfileFiles',
+            'contractTemplateFiles',
+            'migrationProfileFiles',
+            'conventionFiles',
+            'helperFiles',
+            'taskRoutingHintFiles',
+            'registrationHintFiles',
+        ]) {
+            const v = contributions[key];
+            if (v === undefined)
+                continue;
+            if (!Array.isArray(v) ||
+                v.some((entry) => typeof entry !== 'string' || entry.length === 0)) {
+                issues.push({
+                    field: `contributions.${key}`,
+                    message: 'must be an array of non-empty strings',
+                });
+            }
+        }
+    }
+    return { valid: issues.length === 0, issues };
+}
+/**
+ * Convenience for pack authors to write a manifest with type help.
+ */
+export function definePackManifest(input) {
+    return input;
+}

package/dist/pack-signing.d.ts

@@ -0,0 +1,50 @@
+import type { ISharkCraftPackManifest, ISharkCraftPackSignature } from './pack-manifest.js';
+export declare const PACK_SECRET_ENV = "SHARKCRAFT_PACK_SECRET";
+export declare const PACK_SIGNATURE_ALGO = "sha256";
+/**
+ * Well-known dev secret. Any developer can produce a dev signature
+ * mid-session without holding the release secret. The dev secret only
+ * proves "someone signed this with the dev tooling"; release paths reject
+ * dev signatures unless `--allow-dev-signature` is set.
+ */
+export declare const PACK_DEV_SECRET = "sharkcraft-dev-signature-not-for-release";
+/**
+ * Canonical JSON for the signed portion of a pack manifest. Excludes the
+ * signature field itself so the signature can be inserted afterwards without
+ * disturbing the digest.
+ */
+export declare function canonicalizePackManifest(manifest: ISharkCraftPackManifest): string;
+export interface SignPackManifestOptions {
+    secret?: string;
+    keyId?: string;
+    /**
+     * When true, use the well-known dev secret and mark the signature
+     * `dev: true`. Lets agents sign mid-session without the release secret;
+     * release apply paths reject dev signatures unless explicitly allowed.
+     */
+    dev?: boolean;
+}
+export type SignPackResult = {
+    ok: true;
+    manifest: ISharkCraftPackManifest;
+    signature: ISharkCraftPackSignature;
+} | {
+    ok: false;
+    status: 'missing-secret';
+    message: string;
+};
+export declare function signPackManifest(manifest: ISharkCraftPackManifest, options?: SignPackManifestOptions): SignPackResult;
+export type VerifyPackResult = {
+    ok: true;
+    status: 'verified';
+    dev: boolean;
+} | {
+    ok: false;
+    status: 'missing-signature' | 'missing-secret' | 'invalid-signature';
+    message: string;
+};
+export interface VerifyPackManifestOptions {
+    secret?: string;
+}
+export declare function verifyPackManifest(manifest: ISharkCraftPackManifest, options?: VerifyPackManifestOptions): VerifyPackResult;
+//# sourceMappingURL=pack-signing.d.ts.map

package/dist/pack-signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-signing.d.ts","sourceRoot":"","sources":["../src/pack-signing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAE5F,eAAO,MAAM,eAAe,2BAA2B,CAAC;AACxD,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAC5C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,6CAA6C,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,CAGlF;AAwBD,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,uBAAuB,CAAC;IAAC,SAAS,EAAE,wBAAwB,CAAA;CAAE,GACpF;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,uBAAuB,EACjC,OAAO,GAAE,uBAA4B,GACpC,cAAc,CA2BhB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC9C;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,uBAAuB,EACjC,OAAO,GAAE,yBAA8B,GACtC,gBAAgB,CAuClB"}

package/dist/pack-signing.js

@@ -0,0 +1,114 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export const PACK_SECRET_ENV = 'SHARKCRAFT_PACK_SECRET';
+export const PACK_SIGNATURE_ALGO = 'sha256';
+/**
+ * Well-known dev secret. Any developer can produce a dev signature
+ * mid-session without holding the release secret. The dev secret only
+ * proves "someone signed this with the dev tooling"; release paths reject
+ * dev signatures unless `--allow-dev-signature` is set.
+ */
+export const PACK_DEV_SECRET = 'sharkcraft-dev-signature-not-for-release';
+/**
+ * Canonical JSON for the signed portion of a pack manifest. Excludes the
+ * signature field itself so the signature can be inserted afterwards without
+ * disturbing the digest.
+ */
+export function canonicalizePackManifest(manifest) {
+    const { signature: _signature, ...rest } = manifest;
+    return canonicalJson(rest);
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => canonicalJson(v)).join(',') + ']';
+    }
+    const keys = Object.keys(value).sort();
+    const parts = [];
+    for (const k of keys) {
+        const v = value[k];
+        if (v === undefined)
+            continue;
+        parts.push(JSON.stringify(k) + ':' + canonicalJson(v));
+    }
+    return '{' + parts.join(',') + '}';
+}
+function readSecret(secret) {
+    if (secret !== undefined && secret.length > 0)
+        return secret;
+    const fromEnv = process.env[PACK_SECRET_ENV];
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    return null;
+}
+export function signPackManifest(manifest, options = {}) {
+    // Dev mode: use the well-known dev secret. Real secret (env / flag)
+    // is ignored in dev mode so the signature stays portable and verifiable
+    // by any verifier that opts into dev verification.
+    const useDev = options.dev === true;
+    const secret = useDev ? PACK_DEV_SECRET : readSecret(options.secret);
+    if (!secret) {
+        return {
+            ok: false,
+            status: 'missing-secret',
+            message: `Cannot sign pack manifest: set ${PACK_SECRET_ENV} or pass --secret (or use --dev for a non-release dev signature).`,
+        };
+    }
+    const canon = canonicalizePackManifest(manifest);
+    const hmac = createHmac(PACK_SIGNATURE_ALGO, secret).update(canon).digest('hex');
+    const signature = {
+        algo: PACK_SIGNATURE_ALGO,
+        hmac,
+        signedAt: new Date().toISOString(),
+    };
+    if (options.keyId !== undefined)
+        signature.keyId = options.keyId;
+    if (useDev)
+        signature.dev = true;
+    return {
+        ok: true,
+        manifest: { ...manifest, signature },
+        signature,
+    };
+}
+export function verifyPackManifest(manifest, options = {}) {
+    const sig = manifest.signature;
+    if (!sig) {
+        return { ok: false, status: 'missing-signature', message: 'Manifest has no signature.' };
+    }
+    if (sig.algo !== PACK_SIGNATURE_ALGO) {
+        return {
+            ok: false,
+            status: 'invalid-signature',
+            message: `Unsupported signature algorithm: ${sig.algo}`,
+        };
+    }
+    // Dev signatures verify against the well-known dev secret. Callers
+    // see `dev: true` in the result and can choose to reject (release path) or
+    // accept (local-only flows).
+    const isDev = sig.dev === true;
+    const secret = isDev ? PACK_DEV_SECRET : readSecret(options.secret);
+    if (!secret) {
+        return {
+            ok: false,
+            status: 'missing-secret',
+            message: `Cannot verify pack manifest: set ${PACK_SECRET_ENV} or pass --secret.`,
+        };
+    }
+    const canon = canonicalizePackManifest(manifest);
+    const expected = createHmac(PACK_SIGNATURE_ALGO, secret).update(canon).digest();
+    let given;
+    try {
+        given = Buffer.from(sig.hmac, 'hex');
+    }
+    catch {
+        return { ok: false, status: 'invalid-signature', message: 'Signature is not valid hex.' };
+    }
+    if (given.length !== expected.length) {
+        return { ok: false, status: 'invalid-signature', message: 'Signature length mismatch.' };
+    }
+    if (!timingSafeEqual(given, expected)) {
+        return { ok: false, status: 'invalid-signature', message: 'Signature does not match.' };
+    }
+    return { ok: true, status: 'verified', dev: isDev };
+}

package/dist/playbook.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Playbooks: named, reusable human/agent recipes. A playbook bundles a
+ * preset, a pipeline, recommended templates, and a step-by-step runbook
+ * with optional verification commands and safety notes. They're the
+ * generic equivalent of older project-specific recipes without baking
+ * those into the SharkCraft engine.
+ *
+ * Playbooks are NEVER auto-executed; they are structured runbooks that the
+ * agent or human reads and follows.
+ */
+export interface IPlaybookStep {
+    id: string;
+    title: string;
+    description?: string;
+    /** Shell commands to run (read-only / non-destructive recommended). */
+    commands?: readonly string[];
+    /** MCP tools to call to discover context. */
+    mcpTools?: readonly string[];
+    /** When true, this step requires explicit human review before continuing. */
+    humanReview?: boolean;
+    /** Commands the human should run to validate the step's effect. */
+    verificationCommands?: readonly string[];
+    /** Free-form safety notes. */
+    safetyNotes?: readonly string[];
+}
+export interface IPlaybookInput {
+    id: string;
+    title: string;
+    description?: string;
+    tags?: readonly string[];
+    /** Task kinds this playbook is suitable for (e.g. 'generate', 'review'). */
+    taskKinds?: readonly string[];
+    recommendedPresetIds?: readonly string[];
+    recommendedPipelineIds?: readonly string[];
+    recommendedTemplateIds?: readonly string[];
+    steps: readonly IPlaybookStep[];
+    /** Expected outputs after the playbook completes. */
+    outputs?: readonly string[];
+    /** Example tasks the playbook addresses. */
+    examples?: readonly string[];
+}
+export declare function definePlaybook(input: IPlaybookInput): IPlaybookInput;
+//# sourceMappingURL=playbook.d.ts.map

package/dist/playbook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook.d.ts","sourceRoot":"","sources":["../src/playbook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,8BAA8B;IAC9B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,qDAAqD;IACrD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,CAEpE"}

package/dist/playbook.js

@@ -0,0 +1,13 @@
+/**
+ * Playbooks: named, reusable human/agent recipes. A playbook bundles a
+ * preset, a pipeline, recommended templates, and a step-by-step runbook
+ * with optional verification commands and safety notes. They're the
+ * generic equivalent of older project-specific recipes without baking
+ * those into the SharkCraft engine.
+ *
+ * Playbooks are NEVER auto-executed; they are structured runbooks that the
+ * agent or human reads and follows.
+ */
+export function definePlaybook(input) {
+    return input;
+}

package/dist/plugin-lifecycle-profile.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Plugin lifecycle profile (generic).
+ *
+ * A pack can contribute one or more lifecycle profiles describing where its
+ * plugins live, what their barrels and key-tables look like, and which
+ * registry files participate. The engine reads these profiles and plans
+ * plugin rename / remove operations against them.
+ *
+ * The engine never embeds project-specific plugin layouts; all of that comes
+ * from a profile. Pack contributions are static data — no executable code.
+ */
+export declare enum PluginLifecycleRootKind {
+    Api = "api",
+    Cross = "cross",
+    Ui = "ui",
+    Angular = "angular",
+    React = "react",
+    Node = "node",
+    Runtime = "runtime",
+    Other = "other"
+}
+export interface IPluginLifecycleRoot {
+    readonly id: string;
+    readonly path: string;
+    readonly kind?: PluginLifecycleRootKind;
+    readonly pluginFolderSegment?: string;
+}
+export declare enum BarrelSort {
+    Alphabetical = "alphabetical",
+    Preserve = "preserve",
+    Append = "append"
+}
+export interface IPluginLifecycleBarrel {
+    readonly id: string;
+    readonly path: string;
+    readonly exportSegment?: string;
+    readonly sort?: BarrelSort;
+}
+export declare enum CaseStyle {
+    UpperSnake = "upperSnake",
+    Pascal = "pascal",
+    Camel = "camel",
+    Kebab = "kebab"
+}
+export interface IPluginLifecycleKeyTable {
+    readonly path: string;
+    readonly keyCase: CaseStyle;
+    readonly valueCase: CaseStyle;
+    readonly entryAnchor?: string;
+    readonly id?: string;
+}
+export declare enum PluginRegistryFileKind {
+    PluginKey = "plugin-key",
+    UserPluginEntry = "user-plugin-entry",
+    Defaults = "defaults",
+    Event = "event",
+    Command = "command",
+    Composer = "composer",
+    Other = "other"
+}
+export interface IPluginLifecycleRegistryFile {
+    readonly id: string;
+    readonly path: string;
+    readonly kind: PluginRegistryFileKind;
+    readonly entryPattern?: string;
+}
+export interface IPluginLifecycleNaming {
+    readonly pluginIdCase?: CaseStyle;
+    readonly classNameSuffix?: string;
+}
+export interface IPluginLifecycleProfile {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly pluginRoots: readonly IPluginLifecycleRoot[];
+    readonly barrels?: readonly IPluginLifecycleBarrel[];
+    readonly keyTable?: IPluginLifecycleKeyTable;
+    readonly registryFiles?: readonly IPluginLifecycleRegistryFile[];
+    readonly naming?: IPluginLifecycleNaming;
+    readonly validationCommands?: readonly string[];
+    readonly safetyNotes?: readonly string[];
+    readonly appliesWhen?: readonly string[];
+    readonly tags?: readonly string[];
+}
+export interface IPluginLifecycleProfileValidationIssue {
+    readonly field: string;
+    readonly message: string;
+}
+export interface IPluginLifecycleProfileValidationResult {
+    readonly valid: boolean;
+    readonly issues: readonly IPluginLifecycleProfileValidationIssue[];
+}
+/**
+ * Validate a plugin lifecycle profile shape. Lightweight runtime check; no
+ * dependency on zod (plugin-api stays dependency-light, like pack-manifest).
+ */
+export declare function validatePluginLifecycleProfile(value: unknown): IPluginLifecycleProfileValidationResult;
+//# sourceMappingURL=plugin-lifecycle-profile.d.ts.map

package/dist/plugin-lifecycle-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-lifecycle-profile.d.ts","sourceRoot":"","sources":["../src/plugin-lifecycle-profile.ts"],"names":[],"mappings":"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"}

package/dist/plugin-lifecycle-profile.js

@@ -0,0 +1,119 @@
+/**
+ * Plugin lifecycle profile (generic).
+ *
+ * A pack can contribute one or more lifecycle profiles describing where its
+ * plugins live, what their barrels and key-tables look like, and which
+ * registry files participate. The engine reads these profiles and plans
+ * plugin rename / remove operations against them.
+ *
+ * The engine never embeds project-specific plugin layouts; all of that comes
+ * from a profile. Pack contributions are static data — no executable code.
+ */
+export var PluginLifecycleRootKind;
+(function (PluginLifecycleRootKind) {
+    PluginLifecycleRootKind["Api"] = "api";
+    PluginLifecycleRootKind["Cross"] = "cross";
+    PluginLifecycleRootKind["Ui"] = "ui";
+    PluginLifecycleRootKind["Angular"] = "angular";
+    PluginLifecycleRootKind["React"] = "react";
+    PluginLifecycleRootKind["Node"] = "node";
+    PluginLifecycleRootKind["Runtime"] = "runtime";
+    PluginLifecycleRootKind["Other"] = "other";
+})(PluginLifecycleRootKind || (PluginLifecycleRootKind = {}));
+export var BarrelSort;
+(function (BarrelSort) {
+    BarrelSort["Alphabetical"] = "alphabetical";
+    BarrelSort["Preserve"] = "preserve";
+    BarrelSort["Append"] = "append";
+})(BarrelSort || (BarrelSort = {}));
+export var CaseStyle;
+(function (CaseStyle) {
+    CaseStyle["UpperSnake"] = "upperSnake";
+    CaseStyle["Pascal"] = "pascal";
+    CaseStyle["Camel"] = "camel";
+    CaseStyle["Kebab"] = "kebab";
+})(CaseStyle || (CaseStyle = {}));
+export var PluginRegistryFileKind;
+(function (PluginRegistryFileKind) {
+    PluginRegistryFileKind["PluginKey"] = "plugin-key";
+    PluginRegistryFileKind["UserPluginEntry"] = "user-plugin-entry";
+    PluginRegistryFileKind["Defaults"] = "defaults";
+    PluginRegistryFileKind["Event"] = "event";
+    PluginRegistryFileKind["Command"] = "command";
+    PluginRegistryFileKind["Composer"] = "composer";
+    PluginRegistryFileKind["Other"] = "other";
+})(PluginRegistryFileKind || (PluginRegistryFileKind = {}));
+/**
+ * Validate a plugin lifecycle profile shape. Lightweight runtime check; no
+ * dependency on zod (plugin-api stays dependency-light, like pack-manifest).
+ */
+export function validatePluginLifecycleProfile(value) {
+    const issues = [];
+    if (!value || typeof value !== 'object') {
+        return { valid: false, issues: [{ field: '<root>', message: 'profile must be an object' }] };
+    }
+    const obj = value;
+    if (typeof obj.id !== 'string' || obj.id.length === 0) {
+        issues.push({ field: 'id', message: 'id must be a non-empty string' });
+    }
+    if (typeof obj.title !== 'string' || obj.title.length === 0) {
+        issues.push({ field: 'title', message: 'title must be a non-empty string' });
+    }
+    if (!Array.isArray(obj.pluginRoots) || obj.pluginRoots.length === 0) {
+        issues.push({ field: 'pluginRoots', message: 'pluginRoots must be a non-empty array' });
+    }
+    else {
+        obj.pluginRoots.forEach((root, idx) => {
+            if (!root || typeof root !== 'object') {
+                issues.push({ field: `pluginRoots[${idx}]`, message: 'root must be an object' });
+                return;
+            }
+            const r = root;
+            if (typeof r.id !== 'string' || r.id.length === 0) {
+                issues.push({ field: `pluginRoots[${idx}].id`, message: 'id required' });
+            }
+            if (typeof r.path !== 'string' || r.path.length === 0) {
+                issues.push({ field: `pluginRoots[${idx}].path`, message: 'path required' });
+            }
+        });
+    }
+    if (obj.barrels !== undefined) {
+        if (!Array.isArray(obj.barrels)) {
+            issues.push({ field: 'barrels', message: 'barrels must be an array' });
+        }
+        else {
+            obj.barrels.forEach((b, idx) => {
+                if (!b || typeof b !== 'object') {
+                    issues.push({ field: `barrels[${idx}]`, message: 'barrel must be an object' });
+                    return;
+                }
+                const br = b;
+                if (typeof br.id !== 'string' || br.id.length === 0) {
+                    issues.push({ field: `barrels[${idx}].id`, message: 'id required' });
+                }
+                if (typeof br.path !== 'string' || br.path.length === 0) {
+                    issues.push({ field: `barrels[${idx}].path`, message: 'path required' });
+                }
+            });
+        }
+    }
+    if (obj.keyTable !== undefined && obj.keyTable !== null) {
+        const k = obj.keyTable;
+        if (typeof k !== 'object') {
+            issues.push({ field: 'keyTable', message: 'keyTable must be an object' });
+        }
+        else {
+            if (typeof k.path !== 'string' || k.path.length === 0) {
+                issues.push({ field: 'keyTable.path', message: 'path required' });
+            }
+            const validCase = new Set(['upperSnake', 'pascal', 'camel', 'kebab']);
+            if (typeof k.keyCase !== 'string' || !validCase.has(k.keyCase)) {
+                issues.push({ field: 'keyTable.keyCase', message: 'keyCase must be one of upperSnake|pascal|camel|kebab' });
+            }
+            if (typeof k.valueCase !== 'string' || !validCase.has(k.valueCase)) {
+                issues.push({ field: 'keyTable.valueCase', message: 'valueCase must be one of upperSnake|pascal|camel|kebab' });
+            }
+        }
+    }
+    return { valid: issues.length === 0, issues };
+}

package/dist/policy-check.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pack-contributed policy check declaration. Packs that ship
+ * `policyCheckFiles` default-export an array of these definitions.
+ *
+ * SharkCraft's policy engine executes the predicate against the current
+ * inspection plus plan/bundle targets. A predicate must be a pure function
+ * (no shell, no network).
+ */
+export type PolicySeverityLabel = 'info' | 'warning' | 'error' | 'critical';
+export type PolicyCheckTypeLabel = 'path' | 'import' | 'ownership' | 'command' | 'template' | 'plan' | 'bundle' | 'session';
+export interface IPackPolicyCheckEvaluation {
+    message: string;
+    suggestedFix?: string;
+    context?: Record<string, unknown>;
+}
+export interface IPackPolicyCheck {
+    id: string;
+    title: string;
+    severity?: PolicySeverityLabel;
+    checkType?: PolicyCheckTypeLabel;
+    evaluate: (input: {
+        projectRoot: string;
+        planTargets: readonly string[];
+        bundleAffectedFiles: readonly string[];
+    }) => boolean | IPackPolicyCheckEvaluation;
+}
+export declare function definePackPolicyCheck(check: IPackPolicyCheck): IPackPolicyCheck;
+//# sourceMappingURL=policy-check.d.ts.map

package/dist/policy-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-check.d.ts","sourceRoot":"","sources":["../src/policy-check.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE5E,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN,QAAQ,GACR,WAAW,GACX,SAAS,GACT,UAAU,GACV,MAAM,GACN,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,QAAQ,EAAE,CAAC,KAAK,EAAE;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;QAC/B,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;KACxC,KAAK,OAAO,GAAG,0BAA0B,CAAC;CAC5C;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAE/E"}

package/dist/policy-check.js

@@ -0,0 +1,3 @@
+export function definePackPolicyCheck(check) {
+    return check;
+}