@shrkcrft/plugin-api 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/plugin-api
+
+SharkCraft plugin API: extension points for commands, knowledge, templates, MCP tools.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/plugin-api
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/ai-provider-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { ISharkCraftPlugin } from './sharkcraft-plugin.js';
+export interface IAiProviderRegistration {
+    providerId: string;
+    providerName: string;
+}
+export interface IAiProviderPlugin extends ISharkCraftPlugin {
+    readonly providers: readonly IAiProviderRegistration[];
+}
+//# sourceMappingURL=ai-provider-plugin.d.ts.map

package/dist/ai-provider-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-provider-plugin.d.ts","sourceRoot":"","sources":["../src/ai-provider-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACxD"}

package/dist/ai-provider-plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/command-plugin.d.ts

@@ -0,0 +1,11 @@
+import type { ISharkCraftPlugin } from './sharkcraft-plugin.js';
+export interface ICommandPluginCommand {
+    name: string;
+    description: string;
+    /** Returns exit code: 0 success, non-zero failure. */
+    run: (args: readonly string[]) => Promise<number> | number;
+}
+export interface ICommandPlugin extends ISharkCraftPlugin {
+    readonly commands: readonly ICommandPluginCommand[];
+}
+//# sourceMappingURL=command-plugin.d.ts.map

package/dist/command-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-plugin.d.ts","sourceRoot":"","sources":["../src/command-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,GAAG,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CAC5D;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACrD"}

package/dist/command-plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/construct.d.ts

@@ -0,0 +1,57 @@
+/**
+ * SharkCraft constructs: a generic, project-agnostic system for modeling
+ * "the thing this codebase calls X" — plugins, services, modules, features,
+ * etc. A construct bundles together files, public API entries, events,
+ * tokens, commands, and related knowledge / rules / templates so that
+ * `shrk constructs trace <id>` can give a single coherent view.
+ *
+ * Constructs intentionally have no hardcoded "type" set. The `type` field is
+ * a free string so packs can model their own domain (one project might
+ * use 'plugin' / 'policy' / 'capability'; another might use 'service' /
+ * 'module' / 'feature').
+ */
+export interface IConstructFacetValue {
+    /** Stable id within the facet. */
+    id: string;
+    /** The actual value (e.g. event topic, token name). */
+    value: string;
+    description?: string;
+    source?: string;
+}
+export interface IConstructInput {
+    id: string;
+    type: string;
+    title: string;
+    description?: string;
+    tags?: readonly string[];
+    /** Files belonging to the construct (relative to projectRoot). */
+    files?: readonly string[];
+    /** Public-API entries (re-exports, entrypoint files, named exports). */
+    publicApi?: readonly string[];
+    /** Stable event topics emitted / consumed by this construct. */
+    events?: readonly string[];
+    /** Stable token names (DI / capability / config keys). */
+    tokens?: readonly string[];
+    /** CLI / shell commands attached to the construct. */
+    commands?: readonly string[];
+    /** Knowledge ids related to this construct. */
+    relatedKnowledge?: readonly string[];
+    relatedRules?: readonly string[];
+    relatedTemplates?: readonly string[];
+    relatedPipelines?: readonly string[];
+    relatedPathConventions?: readonly string[];
+    /** Free-form facets keyed by name (e.g. capabilities, hooks, …). */
+    facets?: Record<string, readonly IConstructFacetValue[]>;
+}
+export declare function defineConstruct(input: IConstructInput): IConstructInput;
+export interface IConstructFacetInput {
+    id: string;
+    constructId: string;
+    /** Free-string kind: 'event' | 'token' | 'api' | 'file' | 'command' | … */
+    kind: string;
+    value: string;
+    description?: string;
+    source?: string;
+}
+export declare function defineConstructFacet(input: IConstructFacetInput): IConstructFacetInput;
+//# sourceMappingURL=construct.d.ts.map

package/dist/construct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"construct.d.ts","sourceRoot":"","sources":["../src/construct.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,kEAAkE;IAClE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,wEAAwE;IACxE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,gEAAgE;IAChE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC,CAAC;CAC1D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAEvE;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,CAEtF"}

package/dist/construct.js

@@ -0,0 +1,18 @@
+/**
+ * SharkCraft constructs: a generic, project-agnostic system for modeling
+ * "the thing this codebase calls X" — plugins, services, modules, features,
+ * etc. A construct bundles together files, public API entries, events,
+ * tokens, commands, and related knowledge / rules / templates so that
+ * `shrk constructs trace <id>` can give a single coherent view.
+ *
+ * Constructs intentionally have no hardcoded "type" set. The `type` field is
+ * a free string so packs can model their own domain (one project might
+ * use 'plugin' / 'policy' / 'capability'; another might use 'service' /
+ * 'module' / 'feature').
+ */
+export function defineConstruct(input) {
+    return input;
+}
+export function defineConstructFacet(input) {
+    return input;
+}

package/dist/convention.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Generic naming / path / barrel / layout convention.
+ *
+ * Packs and local config contribute conventions via `conventionFiles[]`.
+ * The engine has zero built-in conventions; everything comes from
+ * contributions.
+ *
+ * A convention is static data — no executable code. Rules describe
+ * patterns to expect / forbid; the engine matches files against them.
+ */
+export declare enum ConventionKind {
+    Path = "path",
+    Naming = "naming",
+    Barrel = "barrel",
+    Layout = "layout",
+    Command = "command",
+    Validation = "validation",
+    Ownership = "ownership",
+    Testing = "testing",
+    Release = "release",
+    Safety = "safety"
+}
+export declare enum ConventionSeverity {
+    Info = "info",
+    Warning = "warning",
+    Error = "error"
+}
+export interface IConventionAppliesTo {
+    readonly languages?: readonly string[];
+    readonly frameworks?: readonly string[];
+    readonly fileGlobs?: readonly string[];
+    readonly constructKinds?: readonly string[];
+    readonly profileIds?: readonly string[];
+}
+export interface IConventionRule {
+    readonly id: string;
+    readonly description: string;
+    /** Optional regex describing what *should* match. */
+    readonly expectMatch?: string;
+    /** Optional regex describing what *must not* match. */
+    readonly forbidMatch?: string;
+    /** Optional file-name pattern. */
+    readonly filePattern?: string;
+    /** Optional severity override for this rule (else parent severity). */
+    readonly severity?: ConventionSeverity;
+}
+export interface IConventionExample {
+    readonly description: string;
+    readonly good?: readonly string[];
+    readonly bad?: readonly string[];
+}
+export interface IConventionReference {
+    readonly kind: 'file' | 'doc' | 'command' | 'knowledge' | 'rule';
+    readonly value: string;
+}
+export interface IConvention {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly kind: ConventionKind;
+    readonly appliesTo?: IConventionAppliesTo;
+    readonly rules: readonly IConventionRule[];
+    readonly examples?: readonly IConventionExample[];
+    readonly references?: readonly IConventionReference[];
+    readonly severity: ConventionSeverity;
+    readonly tags?: readonly string[];
+}
+export interface IConventionValidationIssue {
+    readonly field: string;
+    readonly message: string;
+}
+export interface IConventionValidationResult {
+    readonly valid: boolean;
+    readonly issues: readonly IConventionValidationIssue[];
+}
+export declare function validateConvention(value: unknown): IConventionValidationResult;
+//# sourceMappingURL=convention.d.ts.map

package/dist/convention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convention.d.ts","sourceRoot":"","sources":["../src/convention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,MAAM,WAAW;CAClB;AAED,oBAAY,kBAAkB;IAC5B,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACtD,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACxD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,2BAA2B,CAoB9E"}

package/dist/convention.js

@@ -0,0 +1,50 @@
+/**
+ * Generic naming / path / barrel / layout convention.
+ *
+ * Packs and local config contribute conventions via `conventionFiles[]`.
+ * The engine has zero built-in conventions; everything comes from
+ * contributions.
+ *
+ * A convention is static data — no executable code. Rules describe
+ * patterns to expect / forbid; the engine matches files against them.
+ */
+export var ConventionKind;
+(function (ConventionKind) {
+    ConventionKind["Path"] = "path";
+    ConventionKind["Naming"] = "naming";
+    ConventionKind["Barrel"] = "barrel";
+    ConventionKind["Layout"] = "layout";
+    ConventionKind["Command"] = "command";
+    ConventionKind["Validation"] = "validation";
+    ConventionKind["Ownership"] = "ownership";
+    ConventionKind["Testing"] = "testing";
+    ConventionKind["Release"] = "release";
+    ConventionKind["Safety"] = "safety";
+})(ConventionKind || (ConventionKind = {}));
+export var ConventionSeverity;
+(function (ConventionSeverity) {
+    ConventionSeverity["Info"] = "info";
+    ConventionSeverity["Warning"] = "warning";
+    ConventionSeverity["Error"] = "error";
+})(ConventionSeverity || (ConventionSeverity = {}));
+export function validateConvention(value) {
+    const issues = [];
+    if (!value || typeof value !== 'object') {
+        return { valid: false, issues: [{ field: '<root>', message: 'convention 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' });
+    }
+    const knownKinds = new Set(Object.values(ConventionKind));
+    if (typeof obj.kind !== 'string' || !knownKinds.has(obj.kind)) {
+        issues.push({ field: 'kind', message: 'kind must be one of ConventionKind' });
+    }
+    if (!Array.isArray(obj.rules)) {
+        issues.push({ field: 'rules', message: 'rules must be an array' });
+    }
+    return { valid: issues.length === 0, issues };
+}

package/dist/generator-plugin.d.ts

@@ -0,0 +1,6 @@
+import type { ISharkCraftPlugin } from './sharkcraft-plugin.js';
+export interface IGeneratorPlugin extends ISharkCraftPlugin {
+    /** Returns generator IDs this plugin provides. */
+    listGeneratorIds(): readonly string[];
+}
+//# sourceMappingURL=generator-plugin.d.ts.map

package/dist/generator-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-plugin.d.ts","sourceRoot":"","sources":["../src/generator-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,kDAAkD;IAClD,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAAC;CACvC"}

package/dist/generator-plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export * from './sharkcraft-plugin.js';
+export * from './command-plugin.js';
+export * from './knowledge-plugin.js';
+export * from './template-plugin.js';
+export * from './generator-plugin.js';
+export * from './ai-provider-plugin.js';
+export * from './mcp-tool-plugin.js';
+export * from './pack-manifest.js';
+export * from './pack-signing.js';
+export * from './scaffold-pattern.js';
+export * from './construct.js';
+export * from './playbook.js';
+export * from './policy-check.js';
+export * from './search-tuning.js';
+export * from './plugin-lifecycle-profile.js';
+export * from './convention.js';
+export * from './pack-helper.js';
+export * from './task-routing-hint.js';
+export * from './registration-hint.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+export * from "./sharkcraft-plugin.js";
+export * from "./command-plugin.js";
+export * from "./knowledge-plugin.js";
+export * from "./template-plugin.js";
+export * from "./generator-plugin.js";
+export * from "./ai-provider-plugin.js";
+export * from "./mcp-tool-plugin.js";
+export * from "./pack-manifest.js";
+export * from "./pack-signing.js";
+export * from "./scaffold-pattern.js";
+export * from "./construct.js";
+export * from "./playbook.js";
+export * from "./policy-check.js";
+export * from "./search-tuning.js";
+export * from "./plugin-lifecycle-profile.js";
+export * from "./convention.js";
+export * from "./pack-helper.js";
+export * from "./task-routing-hint.js";
+export * from "./registration-hint.js";

package/dist/knowledge-plugin.d.ts

@@ -0,0 +1,15 @@
+import type { ISharkCraftPlugin } from './sharkcraft-plugin.js';
+export interface IKnowledgePluginEntry {
+    id: string;
+    title: string;
+    type: string;
+    priority: string;
+    scope: readonly string[];
+    tags: readonly string[];
+    appliesWhen: readonly string[];
+    content: string;
+}
+export interface IKnowledgePlugin extends ISharkCraftPlugin {
+    readonly entries: readonly IKnowledgePluginEntry[];
+}
+//# sourceMappingURL=knowledge-plugin.d.ts.map

package/dist/knowledge-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-plugin.d.ts","sourceRoot":"","sources":["../src/knowledge-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACpD"}

package/dist/knowledge-plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp-tool-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { ISharkCraftPlugin } from './sharkcraft-plugin.js';
+export interface IMcpToolRegistration {
+    name: string;
+    description: string;
+}
+export interface IMcpToolPlugin extends ISharkCraftPlugin {
+    readonly tools: readonly IMcpToolRegistration[];
+}
+//# sourceMappingURL=mcp-tool-plugin.d.ts.map

package/dist/mcp-tool-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-plugin.d.ts","sourceRoot":"","sources":["../src/mcp-tool-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,QAAQ,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACjD"}

package/dist/mcp-tool-plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/pack-helper.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pack-contributed helper definition.
+ *
+ * Packs can ship project-specific helpers via `helperFiles[]`. Each helper is
+ * static data — no executable pack code beyond declarative operations the
+ * engine understands. The engine plans and previews; never auto-applies.
+ */
+export declare enum PackHelperOutputKind {
+    Preview = "preview",
+    Plan = "plan",
+    Checklist = "checklist"
+}
+export interface IPackHelperSafety {
+    readonly readOnly?: boolean;
+    readonly writesDrafts?: boolean;
+    readonly writesSource?: boolean;
+    readonly requiresProfile?: boolean;
+    readonly requiresHumanReview?: boolean;
+    readonly destructivePotential?: boolean;
+    readonly outputKind: PackHelperOutputKind;
+}
+export interface IPackHelperVariable {
+    readonly name: string;
+    readonly required: boolean;
+    readonly description: string;
+    readonly defaultValue?: string;
+}
+export interface IPackHelperOperationInput {
+    readonly kind: 'append-line' | 'insert-before' | 'replace-line' | 'remove-line' | 'manual-checklist';
+    readonly targetPath?: string;
+    readonly anchor?: string;
+    readonly snippet?: string;
+    readonly find?: string;
+    readonly replaceWith?: string;
+    readonly checklist?: readonly string[];
+    readonly description: string;
+}
+export interface IPackHelper {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly variables: readonly IPackHelperVariable[];
+    /**
+     * Declarative operation list. The engine renders these as plan v2 ops
+     * (no arbitrary pack code execution). When `operations` is empty, the
+     * helper acts as a checklist generator only.
+     */
+    readonly operations?: readonly IPackHelperOperationInput[];
+    readonly manualChecklist?: readonly string[];
+    readonly tags?: readonly string[];
+    readonly appliesWhen?: readonly string[];
+    readonly safety: IPackHelperSafety;
+}
+export interface IPackHelperValidationIssue {
+    readonly field: string;
+    readonly message: string;
+}
+export interface IPackHelperValidationResult {
+    readonly valid: boolean;
+    readonly issues: readonly IPackHelperValidationIssue[];
+}
+export declare function validatePackHelper(value: unknown): IPackHelperValidationResult;
+//# sourceMappingURL=pack-helper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pack-helper.d.ts","sourceRoot":"","sources":["../src/pack-helper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oBAAY,oBAAoB;IAC9B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,GAAG,cAAc,GAAG,aAAa,GAAG,kBAAkB,CAAC;IACrG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC3D,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACxD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,2BAA2B,CAyB9E"}

package/dist/pack-helper.js

@@ -0,0 +1,40 @@
+/**
+ * Pack-contributed helper definition.
+ *
+ * Packs can ship project-specific helpers via `helperFiles[]`. Each helper is
+ * static data — no executable pack code beyond declarative operations the
+ * engine understands. The engine plans and previews; never auto-applies.
+ */
+export var PackHelperOutputKind;
+(function (PackHelperOutputKind) {
+    PackHelperOutputKind["Preview"] = "preview";
+    PackHelperOutputKind["Plan"] = "plan";
+    PackHelperOutputKind["Checklist"] = "checklist";
+})(PackHelperOutputKind || (PackHelperOutputKind = {}));
+export function validatePackHelper(value) {
+    const issues = [];
+    if (!value || typeof value !== 'object') {
+        return { valid: false, issues: [{ field: '<root>', message: 'helper must be an object' }] };
+    }
+    const o = value;
+    if (typeof o.id !== 'string' || o.id.length === 0) {
+        issues.push({ field: 'id', message: 'id required' });
+    }
+    if (typeof o.title !== 'string' || o.title.length === 0) {
+        issues.push({ field: 'title', message: 'title required' });
+    }
+    if (!Array.isArray(o.variables)) {
+        issues.push({ field: 'variables', message: 'variables must be an array' });
+    }
+    const safety = o.safety;
+    if (!safety || typeof safety !== 'object') {
+        issues.push({ field: 'safety', message: 'safety required' });
+    }
+    else {
+        const validOutput = new Set(['preview', 'plan', 'checklist']);
+        if (typeof safety.outputKind !== 'string' || !validOutput.has(safety.outputKind)) {
+            issues.push({ field: 'safety.outputKind', message: 'outputKind must be preview|plan|checklist' });
+        }
+    }
+    return { valid: issues.length === 0, issues };
+}

package/dist/pack-manifest.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+export interface ISharkCraftPackInfo {
+    /** Package name as published (e.g. "@example/sharkcraft-pack"). */
+    name: string;
+    /** Pack version (typically the package version). */
+    version: string;
+    /** Short human-readable description. */
+    description?: string;
+    /** Author / vendor. */
+    author?: string;
+    /** Homepage / repo URL. */
+    homepage?: string;
+    /** Free-form license string. */
+    license?: string;
+}
+export interface ISharkCraftPackContributions {
+    /** Relative paths (from the pack root) to knowledge files. */
+    knowledgeFiles?: readonly string[];
+    ruleFiles?: readonly string[];
+    pathFiles?: readonly string[];
+    templateFiles?: readonly string[];
+    pipelineFiles?: readonly string[];
+    docsFiles?: readonly string[];
+    /** Preset definition files (default export = array of IPreset). */
+    presetFiles?: readonly string[];
+    /** Boundary rule files (default export = array of IBoundaryRule). */
+    boundaryFiles?: readonly string[];
+    /** Context regression test files. */
+    contextTestFiles?: readonly string[];
+    /** Agent contract test files. */
+    agentTestFiles?: readonly string[];
+    /** Future: MCP tool registrations, AI providers, etc. */
+    mcpToolFiles?: readonly string[];
+    aiProviderFiles?: readonly string[];
+    /** Scaffold pattern files (default export = array of IScaffoldPattern). */
+    scaffoldPatternFiles?: readonly string[];
+    /** Policy check files (default export = array of IPackPolicyCheck). */
+    policyCheckFiles?: readonly string[];
+    /** Construct definition files (default export = array of IConstructInput). */
+    constructFiles?: readonly string[];
+    /** Standalone construct facet files. */
+    constructFacetFiles?: readonly string[];
+    /** Playbook definition files (default export = array of IPlaybookInput). */
+    playbookFiles?: readonly string[];
+    /** Search-tuning definition files (default export = array of ISearchTuning). */
+    searchTuningFiles?: readonly string[];
+    /** Pack-extensible feedback rules (default export = array of IFeedbackRule). */
+    feedbackRuleFiles?: readonly string[];
+    /** TypeScript-authored decision records (default export = array of IDecision). */
+    decisionFiles?: readonly string[];
+    /** Pack-extensible path conventions when separate from `pathFiles`. */
+    pathConventionFiles?: readonly string[];
+    /** Pack-contributed plugin lifecycle profiles. Files default-export `readonly IPluginLifecycleProfile[]`. */
+    pluginLifecycleProfileFiles?: readonly string[];
+    /** Pack-contributed agent-contract templates. Files default-export `readonly IAgentContractTemplate[]`. */
+    contractTemplateFiles?: readonly string[];
+    /** Pack-contributed migration readiness profiles. */
+    migrationProfileFiles?: readonly string[];
+    /** Pack-contributed naming/path/barrel conventions. */
+    conventionFiles?: readonly string[];
+    /** Pack-contributed helpers. Files default-export `readonly IPackHelper[]`. */
+    helperFiles?: readonly string[];
+    /** Pack-contributed task routing hints. Files default-export `readonly ITaskRoutingHint[]`. */
+    taskRoutingHintFiles?: readonly string[];
+    /** Pack-contributed registration hints. Files default-export `readonly IRegistrationHint[]`. */
+    registrationHintFiles?: readonly string[];
+}
+export interface ISharkCraftPackSignature {
+    /** Algorithm marker (HMAC-SHA256). */
+    algo: 'sha256';
+    /** Hex-encoded HMAC over canonical-JSON(info + contributions + postInstallNotes). */
+    hmac: string;
+    /** ISO timestamp of when the manifest was signed. */
+    signedAt: string;
+    /**
+     * Identifier (opaque) of the key used to produce the signature. Lets consumers
+     * keep a registry of trusted key ids — see docs/pack-signing.md.
+     */
+    keyId?: string;
+    /**
+     * When `true`, this signature was produced by the dev/local signing
+     * flow (`shrk packs sign --dev`) and is NOT release-trusted. Apply paths
+     * that require release-level signing must reject dev signatures unless
+     * the caller opts in with `--allow-dev-signature`.
+     *
+     * Dev signatures use a well-known dev secret so any developer can produce
+     * them mid-session without holding the release secret. They are honest
+     * about being dev-only — they do not prove publisher identity.
+     */
+    dev?: boolean;
+}
+export interface ISharkCraftPackManifest {
+    /** Schema marker; reserved for forward compatibility. */
+    schema: 'sharkcraft.pack/v1';
+    info: ISharkCraftPackInfo;
+    contributions: ISharkCraftPackContributions;
+    /** Optional human-readable post-install notes. */
+    postInstallNotes?: readonly string[];
+    /**
+     * Optional HMAC signature over the manifest content. When present, consumers
+     * can verify the manifest hasn't been tampered with by an attacker who
+     * substituted the npm tarball. See {@link signPackManifest}.
+     */
+    signature?: ISharkCraftPackSignature;
+}
+export interface IPackManifestValidationIssue {
+    field: string;
+    message: string;
+}
+export interface IPackManifestValidationResult {
+    valid: boolean;
+    issues: IPackManifestValidationIssue[];
+}
+/**
+ * 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 declare function validatePackManifest(value: unknown): IPackManifestValidationResult;
+/**
+ * Convenience for pack authors to write a manifest with type help.
+ */
+export declare function definePackManifest(input: ISharkCraftPackManifest): ISharkCraftPackManifest;
+//# sourceMappingURL=pack-manifest.d.ts.map