@shrkcrft/plugin-api 0.1.0-alpha.2

package/dist/registration-hint.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Registration hint.
+ *
+ * A registration hint describes a downstream registration step that a
+ * generated construct typically needs (e.g. "register the new plugin in the
+ * composer", "wire the new event into the route table"). Packs contribute
+ * hints; the engine ships none.
+ *
+ * Hints are read-only data. The engine never auto-applies them — it can
+ * preview them via `shrk registrations preview <hintId>` and link them
+ * to templates via `template.metadata.registrationHintIds`.
+ *
+ * Discovery rules:
+ *   - `discovery.targetFile` is a fixed relative path the hint applies to
+ *     when present. If absent, `discovery.targetGlobs` lists candidate paths.
+ *   - When more than one candidate matches, the hint MUST report
+ *     `requiresHumanReview: true` and emit a conflict instead of guessing.
+ */
+export interface IRegistrationHintDiscovery {
+    /** Fixed relative path inside the project root, when known. */
+    readonly targetFile?: string;
+    /** Glob patterns (relative paths). Used when the target file varies. */
+    readonly targetGlobs?: readonly string[];
+    /** Convention id(s) the target must satisfy (used as filter). */
+    readonly conventionIds?: readonly string[];
+    /** Profile ids the hint applies to (e.g. lifecycle profile). */
+    readonly profileIds?: readonly string[];
+}
+export type RegistrationHintOpKind = 'ensure-import' | 'insert-enum-entry' | 'insert-object-entry' | 'insert-before-closing-brace' | 'insert-between-anchors' | 'insert-after' | 'insert-before' | 'append' | 'export';
+export interface IRegistrationHintOperation {
+    readonly kind: RegistrationHintOpKind;
+    /** Anchor literal used by anchor-based ops. */
+    readonly anchor?: string;
+    /** Begin anchor for insert-between-anchors. */
+    readonly beginAnchor?: string;
+    /** End anchor for insert-between-anchors. */
+    readonly endAnchor?: string;
+    /** Container name (interface / class / enum / object literal) for body ops. */
+    readonly containerName?: string;
+    /** Enum identifier for insert-enum-entry. */
+    readonly enumName?: string;
+    /** Object literal identifier for insert-object-entry. */
+    readonly objectName?: string;
+    /** Snippet body. May contain `{{var}}` placeholders. */
+    readonly snippet?: string;
+    /** Idempotency marker. */
+    readonly ifMissing?: string;
+    /** Find text (replace op). */
+    readonly find?: string;
+    /** Replace text (replace op). */
+    readonly replaceWith?: string;
+    /** Symbols (ensure-import / export). */
+    readonly symbols?: readonly string[];
+    /** Module specifier (ensure-import / export). */
+    readonly from?: string;
+}
+export interface IRegistrationHint {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    /**
+     * Variables the hint snippet references (templated via `{{var}}`). When a
+     * `preview` is requested, the engine substitutes these values.
+     */
+    readonly variables?: ReadonlyArray<{
+        readonly name: string;
+        readonly required: boolean;
+        readonly description?: string;
+        readonly defaultValue?: string;
+    }>;
+    readonly discovery: IRegistrationHintDiscovery;
+    /**
+     * The operations that the hint would perform if applied. Today the engine
+     * surfaces these as a *preview* only.
+     */
+    readonly operations: ReadonlyArray<IRegistrationHintOperation>;
+    /** When true, the preview must include a "requires human review" badge. */
+    readonly requiresHumanReview?: boolean;
+    /** Validation commands recommended after the human applies the hint. */
+    readonly validationCommands?: readonly string[];
+    /** Optional explanatory text shown alongside the preview. */
+    readonly explanation?: string;
+    /** Safety notes shown before any preview. */
+    readonly safetyNotes?: readonly string[];
+    readonly tags?: readonly string[];
+}
+export interface IRegistrationHintValidationIssue {
+    readonly field: string;
+    readonly message: string;
+}
+export interface IRegistrationHintValidationResult {
+    readonly valid: boolean;
+    readonly issues: readonly IRegistrationHintValidationIssue[];
+}
+export declare function validateRegistrationHint(value: unknown): IRegistrationHintValidationResult;
+//# sourceMappingURL=registration-hint.d.ts.map

package/dist/registration-hint.d.ts.map

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

package/dist/registration-hint.js

@@ -0,0 +1,47 @@
+/**
+ * Registration hint.
+ *
+ * A registration hint describes a downstream registration step that a
+ * generated construct typically needs (e.g. "register the new plugin in the
+ * composer", "wire the new event into the route table"). Packs contribute
+ * hints; the engine ships none.
+ *
+ * Hints are read-only data. The engine never auto-applies them — it can
+ * preview them via `shrk registrations preview <hintId>` and link them
+ * to templates via `template.metadata.registrationHintIds`.
+ *
+ * Discovery rules:
+ *   - `discovery.targetFile` is a fixed relative path the hint applies to
+ *     when present. If absent, `discovery.targetGlobs` lists candidate paths.
+ *   - When more than one candidate matches, the hint MUST report
+ *     `requiresHumanReview: true` and emit a conflict instead of guessing.
+ */
+export function validateRegistrationHint(value) {
+    const issues = [];
+    if (!value || typeof value !== 'object') {
+        return { valid: false, issues: [{ field: '<root>', message: 'hint 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 (!o.discovery || typeof o.discovery !== 'object') {
+        issues.push({ field: 'discovery', message: 'discovery required' });
+    }
+    else {
+        const d = o.discovery;
+        const hasFixed = typeof d.targetFile === 'string' && d.targetFile.length > 0;
+        const hasGlobs = Array.isArray(d.targetGlobs) && d.targetGlobs.length > 0;
+        if (!hasFixed && !hasGlobs) {
+            issues.push({
+                field: 'discovery',
+                message: 'discovery requires either targetFile or targetGlobs[]',
+            });
+        }
+    }
+    if (!Array.isArray(o.operations) || o.operations.length === 0) {
+        issues.push({ field: 'operations', message: 'operations[] must be non-empty' });
+    }
+    return { valid: issues.length === 0, issues };
+}

package/dist/scaffold-pattern.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Scaffold patterns let a pack express "if you see a file matching these
+ * paths, suggest this template id with these variables." Inference uses them
+ * to seed `infer templates` / `onboard --scaffold-templates` with high-
+ * confidence candidates without re-implementing pattern matching locally.
+ *
+ * Scaffold patterns are read-only data — they cannot execute code, shell
+ * commands, or run any pack-provided functions. The match step happens in
+ * the inspector layer.
+ */
+/** A single variable extraction strategy. Values are recognized strings. */
+export type ScaffoldExtractionStrategy = 'filename.kebab' | 'filename.pascal' | 'className' | `className.stripPrefix:${string}` | 'functionName' | 'directoryName' | 'nearestPackageName';
+export interface IScaffoldPatternVariable {
+    /** Variable name as exposed to the template renderer (e.g. "name"). */
+    name: string;
+    /** Where the value should come from. */
+    from: ScaffoldExtractionStrategy;
+    /** Optional human description of what this variable represents. */
+    description?: string;
+}
+export interface IScaffoldPattern {
+    /** Stable id, e.g. "myproj.plugin-contract-pattern". */
+    id: string;
+    /** Short human-readable title. */
+    title: string;
+    /** What this pattern detects and where it points. */
+    description: string;
+    /** Glob-like include patterns relative to the project root. */
+    matchPaths: readonly string[];
+    /** Optional exclude patterns. */
+    excludePaths?: readonly string[];
+    /** Template id this pattern suggests when matched. */
+    templateId: string;
+    /** Variable extraction strategies. */
+    variables: readonly IScaffoldPatternVariable[];
+    /** Lifecycle hooks where this pattern is consulted. */
+    appliesWhen: readonly ('onboard' | 'infer-template' | 'create-plugin' | string)[];
+    /** Confidence floor when matched. */
+    confidence: 'high' | 'medium' | 'low';
+    /** Free-form tags for grouping. */
+    tags?: readonly string[];
+    /** Optional notes shown in pack doctor / scaffolds list. */
+    notes?: readonly string[];
+    /**
+     * Optional evidence the inspector should check before accepting the match
+     * (e.g. "the file exports an interface starting with I"). Strings only —
+     * the actual checks are inspector-side.
+     */
+    requiredEvidence?: readonly string[];
+}
+export declare function defineScaffoldPattern(pattern: IScaffoldPattern): IScaffoldPattern;
+/** Helper used by pack authors to ship an array of scaffold patterns. */
+export declare function defineScaffoldPatterns(patterns: readonly IScaffoldPattern[]): readonly IScaffoldPattern[];
+export declare const RECOGNIZED_SCAFFOLD_STRATEGIES: ReadonlySet<string>;
+export declare function isRecognizedScaffoldStrategy(s: string): boolean;
+//# sourceMappingURL=scaffold-pattern.d.ts.map

package/dist/scaffold-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-pattern.d.ts","sourceRoot":"","sources":["../src/scaffold-pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,0BAA0B,GAClC,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,GACX,yBAAyB,MAAM,EAAE,GACjC,cAAc,GACd,eAAe,GACf,oBAAoB,CAAC;AAEzB,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,EAAE,0BAA0B,CAAC;IACjC,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,iCAAiC;IACjC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,SAAS,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC/C,uDAAuD;IACvD,WAAW,EAAE,SAAS,CAAC,SAAS,GAAG,gBAAgB,GAAG,eAAe,GAAG,MAAM,CAAC,EAAE,CAAC;IAClF,qCAAqC;IACrC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,mCAAmC;IACnC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAEjF;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,SAAS,gBAAgB,EAAE,CAE7B;AAED,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAO7D,CAAC;AAEH,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAI/D"}

package/dist/scaffold-pattern.js

@@ -0,0 +1,32 @@
+/**
+ * Scaffold patterns let a pack express "if you see a file matching these
+ * paths, suggest this template id with these variables." Inference uses them
+ * to seed `infer templates` / `onboard --scaffold-templates` with high-
+ * confidence candidates without re-implementing pattern matching locally.
+ *
+ * Scaffold patterns are read-only data — they cannot execute code, shell
+ * commands, or run any pack-provided functions. The match step happens in
+ * the inspector layer.
+ */
+export function defineScaffoldPattern(pattern) {
+    return pattern;
+}
+/** Helper used by pack authors to ship an array of scaffold patterns. */
+export function defineScaffoldPatterns(patterns) {
+    return patterns;
+}
+export const RECOGNIZED_SCAFFOLD_STRATEGIES = new Set([
+    'filename.kebab',
+    'filename.pascal',
+    'className',
+    'functionName',
+    'directoryName',
+    'nearestPackageName',
+]);
+export function isRecognizedScaffoldStrategy(s) {
+    if (RECOGNIZED_SCAFFOLD_STRATEGIES.has(s))
+        return true;
+    if (s.startsWith('className.stripPrefix:'))
+        return true;
+    return false;
+}

package/dist/search-tuning.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Search tuning lets packs/local config bias SharkCraft's deterministic search
+ * ranker. It NEVER filters results — only nudges scores. Boosts are capped to
+ * keep tuning from dominating the natural signal.
+ */
+export interface ISearchTaskHint {
+    /** Token list (lowercase) that must appear in the query for the hint to apply. */
+    whenTokens?: readonly string[];
+    boostTags?: Record<string, number>;
+    boostKinds?: Record<string, number>;
+    boostIds?: Record<string, number>;
+}
+export type SearchTuningMergeStrategy = 'sum' | 'max';
+export interface ISearchTuning {
+    id: string;
+    /** When set, the tuning only applies to results in these kinds. */
+    appliesToKinds?: readonly string[];
+    /**
+     * How this tuning composes with other tunings touching the same boost key.
+     * - `sum` (default): each tuning's boost adds, then the global cap clips.
+     * - `max`: when any tuning contributing to the key declares `max`, the
+     *   combined boost is the strongest single contributor (by absolute value).
+     *   Useful when packs ship overlapping bias rules and the user wants the
+     *   single most-relevant one to win rather than stacking.
+     */
+    mergeStrategy?: SearchTuningMergeStrategy;
+    boostTags?: Record<string, number>;
+    boostIds?: Record<string, number>;
+    boostSources?: Record<string, number>;
+    taskHints?: readonly ISearchTaskHint[];
+}
+export declare function defineSearchTuning(input: ISearchTuning): ISearchTuning;
+//# sourceMappingURL=search-tuning.d.ts.map

package/dist/search-tuning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tuning.d.ts","sourceRoot":"","sources":["../src/search-tuning.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,yBAAyB,GAAG,KAAK,GAAG,KAAK,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CACxC;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAEtE"}

package/dist/search-tuning.js

@@ -0,0 +1,3 @@
+export function defineSearchTuning(input) {
+    return input;
+}

package/dist/sharkcraft-plugin.d.ts

@@ -0,0 +1,13 @@
+export interface ISharkCraftPluginContext {
+    readonly cwd: string;
+    readonly projectRoot: string;
+    /** Free-form bag for cross-plugin data — do not abuse. */
+    readonly bag: Map<string, unknown>;
+}
+export interface ISharkCraftPlugin {
+    readonly id: string;
+    readonly name: string;
+    readonly version?: string;
+    init?(context: ISharkCraftPluginContext): void | Promise<void>;
+}
+//# sourceMappingURL=sharkcraft-plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharkcraft-plugin.d.ts","sourceRoot":"","sources":["../src/sharkcraft-plugin.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE"}

package/dist/sharkcraft-plugin.js

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

package/dist/task-routing-hint.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Task routing hint. Packs and local config contribute hints that bias
+ * the engine's recommendations (`shrk task`, `shrk context`, `shrk recommend`,
+ * `shrk coverage scaffolds`, `shrk why`) toward their playbooks / templates /
+ * helpers / profiles / conventions without the engine hardcoding any
+ * project-specific tokens.
+ *
+ * Static data only — no executable code.
+ */
+export interface ITaskRoutingMatch {
+    readonly keywords?: readonly string[];
+    readonly phrases?: readonly string[];
+    readonly regexes?: readonly string[];
+    readonly languages?: readonly string[];
+    readonly fileGlobs?: readonly string[];
+    readonly constructKinds?: readonly string[];
+}
+export interface ITaskRoutingRecommends {
+    readonly commands?: readonly string[];
+    readonly templates?: readonly string[];
+    readonly playbooks?: readonly string[];
+    readonly helpers?: readonly string[];
+    readonly profiles?: readonly string[];
+    readonly conventions?: readonly string[];
+    readonly knowledge?: readonly string[];
+    readonly policies?: readonly string[];
+}
+export interface ITaskRoutingHint {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly match: ITaskRoutingMatch;
+    readonly recommends: ITaskRoutingRecommends;
+    /** Tag-/id-level confidence boost (0..5). */
+    readonly confidenceBoost?: number;
+    readonly explanation?: string;
+    readonly safetyNotes?: readonly string[];
+    readonly tags?: readonly string[];
+}
+export interface ITaskRoutingHintValidationIssue {
+    readonly field: string;
+    readonly message: string;
+}
+export interface ITaskRoutingHintValidationResult {
+    readonly valid: boolean;
+    readonly issues: readonly ITaskRoutingHintValidationIssue[];
+}
+export declare function validateTaskRoutingHint(value: unknown): ITaskRoutingHintValidationResult;
+//# sourceMappingURL=task-routing-hint.d.ts.map

package/dist/task-routing-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-routing-hint.d.ts","sourceRoot":"","sources":["../src/task-routing-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC;IAC5C,6CAA6C;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,+BAA+B,EAAE,CAAC;CAC7D;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,gCAAgC,CAmBxF"}

package/dist/task-routing-hint.js

@@ -0,0 +1,29 @@
+/**
+ * Task routing hint. Packs and local config contribute hints that bias
+ * the engine's recommendations (`shrk task`, `shrk context`, `shrk recommend`,
+ * `shrk coverage scaffolds`, `shrk why`) toward their playbooks / templates /
+ * helpers / profiles / conventions without the engine hardcoding any
+ * project-specific tokens.
+ *
+ * Static data only — no executable code.
+ */
+export function validateTaskRoutingHint(value) {
+    const issues = [];
+    if (!value || typeof value !== 'object') {
+        return { valid: false, issues: [{ field: '<root>', message: 'hint 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 (!o.match || typeof o.match !== 'object') {
+        issues.push({ field: 'match', message: 'match required' });
+    }
+    if (!o.recommends || typeof o.recommends !== 'object') {
+        issues.push({ field: 'recommends', message: 'recommends required' });
+    }
+    return { valid: issues.length === 0, issues };
+}

package/dist/template-plugin.d.ts

@@ -0,0 +1,10 @@
+import type { ISharkCraftPlugin } from './sharkcraft-plugin.js';
+export interface ITemplatePluginTemplate {
+    id: string;
+    name: string;
+    description: string;
+}
+export interface ITemplatePlugin extends ISharkCraftPlugin {
+    readonly templates: readonly ITemplatePluginTemplate[];
+}
+//# sourceMappingURL=template-plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"template-plugin.d.ts","sourceRoot":"","sources":["../src/template-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACxD"}

package/dist/template-plugin.js

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@shrkcrft/plugin-api",
+  "version": "0.1.0-alpha.2",
+  "description": "SharkCraft plugin API: extension points for commands, knowledge, templates, MCP tools.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrkcrft/sharkcraft.git",
+    "directory": "packages/plugin-api"
+  },
+  "homepage": "https://github.com/shrkcrft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/shrkcrft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "plugin-api"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}