@ai-plugin-marketplace/core 0.1.0

package/dist/pipeline/sentinel.js

@@ -0,0 +1,263 @@
+/**
+ * Generated-file sentinels.
+ *
+ * Per §4.3 of the architecture spec, every toolkit-generated file carries a sentinel so
+ * hand-edits are detectable by the freshness check (§10.5). There are three carriers:
+ *
+ * 1. **Inline text** — a comment block prepended to plain-text generated files.
+ * 2. **JSON `_generated` field** — a top-level object on JSON outputs that tolerate extra keys.
+ * 3. **Sidecar `<artifact>.generated`** — a companion file holding the inline-text body, used
+ *    for strict-schema hosts that reject unknown top-level fields (Gemini's
+ *    `gemini-extension.json`, Kiro's `.kiro/agents/*.json`).
+ *
+ * This module is **pure**: string/object in, string out. It performs no filesystem I/O — the
+ * build (§5.2) and freshness (§10.5) layers own all reads and writes. It is internal to
+ * `@ai-plugin-marketplace/core` and intentionally NOT re-exported from the package root.
+ *
+ * Round-trip invariants hold for every carrier:
+ * - `stripSentinel(applyXSentinel(x, src), mode) === x`
+ * - `readSentinelSource(applyXSentinel(x, src), mode) === src`
+ *
+ * @see docs/specs/architecture.md §4.3 (author-authored vs toolkit-generated — governing section)
+ * @see docs/specs/architecture.md §10.5 (freshness check — consumer of the detect/strip helpers)
+ * @see docs/specs/architecture.md §5.2 (build phase — consumer of the apply helpers)
+ */
+/**
+ * Canonical generator identity string embedded in every sentinel. Centralized here so the
+ * inline comment block, the JSON `_generated.by` field, and any detector all agree on one
+ * literal — there is no second copy to drift.
+ */
+export const GENERATOR_ID = '@ai-plugin-marketplace/cli';
+// ---------------------------------------------------------------------------
+// Inline-text carrier
+// ---------------------------------------------------------------------------
+/** First line of the inline/sidecar comment body. */
+const INLINE_LINE_1 = `# Generated by ${GENERATOR_ID}. Do not edit directly.`;
+/** Second line of the inline/sidecar comment body. */
+const INLINE_LINE_2 = '# Edit the source file listed in the sentinel and run `aipm build`.';
+/** Prefix of the third (source) line; the relative source path is appended verbatim. */
+const INLINE_SOURCE_PREFIX = '# source: ';
+/**
+ * Build the canonical inline-text sentinel body for a source path. This three-line block is
+ * shared by the inline carrier (prepended to content) and the sidecar carrier (used as the
+ * whole sidecar file). Always terminated by a trailing newline so the following content — or
+ * the file end, for a sidecar — starts on a fresh line.
+ *
+ * @param source - Author-authored source path, relative to the plugin directory.
+ * @returns The three-line comment block, newline-terminated.
+ */
+function inlineSentinelBlock(source) {
+    return `${INLINE_LINE_1}\n${INLINE_LINE_2}\n${INLINE_SOURCE_PREFIX}${source}\n`;
+}
+/**
+ * Prepend the inline-text sentinel (§4.3) to a plain-text generated file's content.
+ *
+ * @param content - The generated file body, sans sentinel.
+ * @param source - Author-authored source path, relative to the plugin directory.
+ * @returns Content with the three-line sentinel block prepended.
+ */
+export function applyInlineSentinel(content, source) {
+    return inlineSentinelBlock(source) + content;
+}
+// ---------------------------------------------------------------------------
+// Sidecar carrier
+// ---------------------------------------------------------------------------
+/** Suffix appended to an artifact path to form its sidecar sentinel path. */
+const SIDECAR_SUFFIX = '.generated';
+/**
+ * The body of a `<artifact>.generated` sidecar file (§4.3). Identical to the inline-text
+ * sentinel block — the sidecar carries no artifact content, only the sentinel.
+ *
+ * @param source - Author-authored source path, relative to the plugin directory.
+ * @returns The three-line sentinel block, newline-terminated.
+ */
+export function sidecarContent(source) {
+    return inlineSentinelBlock(source);
+}
+/**
+ * Derive the sidecar sentinel path for an artifact: `<artifactPath>.generated` (§4.3). The
+ * sidecar sits next to the artifact; the artifact itself is left untouched.
+ *
+ * @param artifactPath - Path to the strict-schema artifact (e.g. `gemini-extension.json`).
+ * @returns The sidecar path.
+ */
+export function sidecarPath(artifactPath) {
+    return `${artifactPath}${SIDECAR_SUFFIX}`;
+}
+// ---------------------------------------------------------------------------
+// JSON `_generated`-field carrier
+// ---------------------------------------------------------------------------
+/**
+ * Serialize an object as canonical JSON with a top-level `_generated` sentinel (§4.3). The
+ * `_generated` key is emitted FIRST, every other own-enumerable key follows in its original
+ * order, and the output uses 2-space indentation with a trailing newline — matching the JSON
+ * conventions in `claude/transform.ts`'s `serializeClaudeHooksJson`.
+ *
+ * Any pre-existing `_generated` key on the input is overwritten by the fresh sentinel rather
+ * than duplicated, so re-applying is idempotent at the field level.
+ *
+ * @param obj - The value to serialize. Treated as a string-keyed object; non-object inputs
+ *   (arrays, primitives) cannot carry a top-level field and are rejected.
+ * @param source - Author-authored source path, relative to the plugin directory.
+ * @returns Canonical JSON string with `_generated` first and a trailing `\n`.
+ * @throws {TypeError} If `obj` is not a plain JSON object (null, array, or primitive).
+ */
+export function applyJsonSentinel(obj, source) {
+    if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+        throw new TypeError('applyJsonSentinel: expected a plain object to carry a top-level _generated field');
+    }
+    const sentinel = { by: GENERATOR_ID, source };
+    // `_generated` first, then every other own key in its original insertion order. Spreading a
+    // pre-existing `_generated` would re-introduce it after ours, so drop it from the rest.
+    const rest = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === '_generated')
+            continue;
+        rest[key] = value;
+    }
+    const withSentinel = { _generated: sentinel, ...rest };
+    return JSON.stringify(withSentinel, null, 2) + '\n';
+}
+/**
+ * Convenience overload for validated Claude hooks data, matching the call shape of
+ * `serializeClaudeHooksJson`. Equivalent to {@link applyJsonSentinel} with the hooks object.
+ *
+ * @param data - Validated {@link ClaudeHooksFile}.
+ * @param source - Author-authored source path, relative to the plugin directory.
+ * @returns Canonical JSON string with `_generated` first and a trailing `\n`.
+ */
+export function applyJsonSentinelToHooks(data, source) {
+    return applyJsonSentinel(data, source);
+}
+// ---------------------------------------------------------------------------
+// Detection / source extraction / stripping (consumed by freshness — §10.5)
+// ---------------------------------------------------------------------------
+/**
+ * Parse JSON content into a string-keyed object, returning `undefined` for malformed JSON or
+ * any non-object top-level value (array, primitive, null). Used by the JSON-carrier detectors
+ * so a hand-corrupted generated file degrades gracefully rather than throwing.
+ */
+function parseJsonObject(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return undefined;
+    }
+    return parsed;
+}
+/**
+ * Read the `source` from a JSON `_generated` field, validating that the field is a well-formed
+ * {@link JsonSentinelField}. Returns `undefined` if absent or malformed.
+ */
+function readJsonSentinelSource(content) {
+    const obj = parseJsonObject(content);
+    if (!obj)
+        return undefined;
+    const generated = obj['_generated'];
+    if (typeof generated !== 'object' || generated === null || Array.isArray(generated)) {
+        return undefined;
+    }
+    const source = generated['source'];
+    return typeof source === 'string' ? source : undefined;
+}
+/**
+ * Read the `source` from an inline/sidecar comment block. Returns `undefined` if the content
+ * does not begin with the canonical two-line preamble followed by a `# source:` line.
+ */
+function readInlineSentinelSource(content) {
+    const lines = content.split('\n');
+    if (lines[0] !== INLINE_LINE_1 || lines[1] !== INLINE_LINE_2)
+        return undefined;
+    const sourceLine = lines[2];
+    if (!sourceLine?.startsWith(INLINE_SOURCE_PREFIX))
+        return undefined;
+    return sourceLine.slice(INLINE_SOURCE_PREFIX.length);
+}
+/**
+ * Detect whether `content` carries a sentinel for the given carrier (§4.3). For `'sidecar'`,
+ * `content` is the sidecar file body (same shape as inline); the artifact itself is never
+ * inspected by this function.
+ *
+ * @param content - File content to inspect (artifact body, or sidecar body for `'sidecar'`).
+ * @param mode - Which carrier to check for.
+ * @returns `true` iff a well-formed sentinel of that carrier is present.
+ */
+export function hasSentinel(content, mode) {
+    return readSentinelSource(content, mode) !== undefined;
+}
+/**
+ * Extract the author-authored source path recorded in a sentinel, or `undefined` if no
+ * well-formed sentinel of the given carrier is present (§10.5 uses this to identify the source
+ * and to distinguish generated files from hand-authored ones).
+ *
+ * @param content - File content to inspect (artifact body, or sidecar body for `'sidecar'`).
+ * @param mode - Which carrier to read.
+ * @returns The recorded source path, or `undefined`.
+ */
+export function readSentinelSource(content, mode) {
+    switch (mode) {
+        case 'inline':
+        case 'sidecar':
+            return readInlineSentinelSource(content);
+        case 'json-field':
+            return readJsonSentinelSource(content);
+    }
+}
+/**
+ * Remove a sentinel from `content`, returning the body sans sentinel. The inverse of the
+ * matching `applyXSentinel`, so freshness (§10.5) can compare an on-disk generated file to
+ * freshly-built content modulo the sentinel.
+ *
+ * - `'inline'` — drops the three-line comment block if present; otherwise returns `content`
+ *   unchanged.
+ * - `'sidecar'` — the sidecar carries only the sentinel, so the stripped body is the empty
+ *   string; if `content` is not a recognized sidecar it is returned unchanged.
+ * - `'json-field'` — re-serializes the object without `_generated`, preserving the remaining
+ *   keys' order, 2-space indent, and trailing newline. Malformed JSON is returned unchanged.
+ *
+ * @param content - File content to strip.
+ * @param mode - Which carrier to strip.
+ * @returns The content with its sentinel removed.
+ */
+export function stripSentinel(content, mode) {
+    switch (mode) {
+        case 'inline':
+            return stripInlineSentinel(content);
+        case 'sidecar':
+            // A sidecar is wholly sentinel; stripping yields an empty body. Leave unrecognized
+            // content untouched so a non-sidecar file is not silently emptied.
+            return hasSentinel(content, 'sidecar') ? '' : content;
+        case 'json-field':
+            return stripJsonSentinel(content);
+    }
+}
+/** Drop the leading three-line inline sentinel block, if present. */
+function stripInlineSentinel(content) {
+    if (readInlineSentinelSource(content) === undefined)
+        return content;
+    // The block is exactly three newline-terminated lines; remove up to and including the third
+    // newline. Locate it without assuming the source path is newline-free beyond line 3.
+    const firstNl = content.indexOf('\n');
+    const secondNl = content.indexOf('\n', firstNl + 1);
+    const thirdNl = content.indexOf('\n', secondNl + 1);
+    return content.slice(thirdNl + 1);
+}
+/** Re-serialize JSON content without its `_generated` field; passthrough on malformed JSON. */
+function stripJsonSentinel(content) {
+    const obj = parseJsonObject(content);
+    if (!obj)
+        return content;
+    const rest = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === '_generated')
+            continue;
+        rest[key] = value;
+    }
+    return JSON.stringify(rest, null, 2) + '\n';
+}
+//# sourceMappingURL=sentinel.js.map

package/dist/pipeline/sentinel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.js","sourceRoot":"","sources":["../../src/pipeline/sentinel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAuBzD,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,qDAAqD;AACrD,MAAM,aAAa,GAAG,kBAAkB,YAAY,yBAAyB,CAAC;AAC9E,sDAAsD;AACtD,MAAM,aAAa,GAAG,qEAAqE,CAAC;AAC5F,wFAAwF;AACxF,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAE1C;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAAC,MAAc;IACzC,OAAO,GAAG,aAAa,KAAK,aAAa,KAAK,oBAAoB,GAAG,MAAM,IAAI,CAAC;AAClF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,MAAc;IACjE,OAAO,mBAAmB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;AAC/C,CAAC;AAED,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,6EAA6E;AAC7E,MAAM,cAAc,GAAG,YAAY,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,YAAoB;IAC9C,OAAO,GAAG,YAAY,GAAG,cAAc,EAAE,CAAC;AAC5C,CAAC;AAED,8EAA8E;AAC9E,kCAAkC;AAClC,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,MAAc;IAC5D,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CACjB,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAsB,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;IAEjE,4FAA4F;IAC5F,wFAAwF;IACxF,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,GAAG,KAAK,YAAY;YAAE,SAAS;QACnC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,MAAM,YAAY,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAC;IACvD,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AACtD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAqB,EAAE,MAAc;IAC5E,OAAO,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAE9E;;;;GAIG;AACH,SAAS,eAAe,CAAC,OAAe;IACtC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,SAAS,sBAAsB,CAAC,OAAe;IAC7C,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,SAAS,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IACpC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACpF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAI,SAAqC,CAAC,QAAQ,CAAC,CAAC;IAChE,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,SAAS,wBAAwB,CAAC,OAAe;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,aAAa,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,aAAa;QAAE,OAAO,SAAS,CAAC;IAC/E,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,oBAAoB,CAAC;QAAE,OAAO,SAAS,CAAC;IACpE,OAAO,UAAU,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,IAAkB;IAC7D,OAAO,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,SAAS,CAAC;AACzD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,IAAkB;IACpE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAC3C,KAAK,YAAY;YACf,OAAO,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,IAAkB;IAC/D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACtC,KAAK,SAAS;YACZ,mFAAmF;YACnF,mEAAmE;YACnE,OAAO,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACxD,KAAK,YAAY;YACf,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED,qEAAqE;AACrE,SAAS,mBAAmB,CAAC,OAAe;IAC1C,IAAI,wBAAwB,CAAC,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACpE,4FAA4F;IAC5F,qFAAqF;IACrF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,+FAA+F;AAC/F,SAAS,iBAAiB,CAAC,OAAe;IACxC,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG;QAAE,OAAO,OAAO,CAAC;IACzB,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,GAAG,KAAK,YAAY;YAAE,SAAS;QACnC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAC9C,CAAC"}

package/dist/pipeline/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Public types for the core API. These are the contract surface per §8.1 of the spec.
+ */
+/**
+ * A host-platform identity. The closed union of target IDs this toolkit version knows about.
+ *
+ * Declared as an explicit literal union (matching the public contract in spec §8.1) rather than
+ * derived from `TARGET_IDS`. This keeps the public type self-contained: a
+ * `typeof TARGET_IDS` derivation would make the published `TargetId` depend on the non-exported
+ * `TARGET_IDS` const, which API Extractor reports as `ae-forgotten-export`. The runtime array
+ * below is validated against this union with `satisfies`, so the two cannot drift.
+ *
+ * @public
+ */
+export type TargetId = 'claude' | 'cursor' | 'gemini' | 'kiro' | 'vercel';
+/**
+ * Canonical list of target IDs known to this toolkit version. Runtime-exposed so
+ * `listTargets()` and config validation share one source of truth.
+ *
+ * `as const satisfies readonly TargetId[]` preserves the literal tuple type (required by
+ * `z.enum`) while guaranteeing every entry is a valid {@link TargetId}. The
+ * `_targetIdsAreExhaustive` assertion below closes the other direction (every {@link TargetId}
+ * appears here), so the union and the array cannot drift in either direction.
+ *
+ * Not part of the public API — `index.ts` re-exports only the `TargetId` type, not this runtime
+ * array. Marked `@internal` so the release-tag lint rule is satisfied without widening the
+ * public surface.
+ *
+ * @internal
+ */
+export declare const TARGET_IDS: readonly ["claude", "cursor", "gemini", "kiro", "vercel"];
+/**
+ * Options for {@link build}.
+ *
+ * @public
+ */
+export interface BuildOptions {
+    /** Abort after the first hard validation finding. Default: false. */
+    failFast?: boolean;
+}
+/**
+ * Result of building a single plugin. One entry per plugin built.
+ *
+ * @public
+ */
+export interface BuildResult {
+    /** Plugin directory name, e.g. 'skill-evaluator'. */
+    plugin: string;
+    /** Absolute path to the plugin directory. */
+    pluginDir: string;
+    /** Every file the build produced or verified as up-to-date. */
+    artifacts: GeneratedFile[];
+    /** Wall-clock time in milliseconds. */
+    durationMs: number;
+}
+/**
+ * A file produced or verified by the build.
+ *
+ * @public
+ */
+export interface GeneratedFile {
+    /** Absolute path. */
+    path: string;
+    /** The author-authored file this was generated from, if applicable. */
+    source?: string;
+    /** Which target's build step produced this file. */
+    target: TargetId;
+}
+/**
+ * Options for {@link validate}.
+ *
+ * @public
+ */
+export interface ValidateOptions {
+    /** When true, skip the freshness check (§10.5). Default: false. */
+    skipFreshness?: boolean;
+}
+/**
+ * Result of validating one or more plugins.
+ *
+ * @public
+ */
+export interface ValidationResult {
+    findings: Finding[];
+    /** True iff no hard findings were emitted. Soft findings do not flip this. */
+    passed: boolean;
+}
+/**
+ * Enumerated finding codes. Additive — new codes arrive in toolkit MINOR releases; removing
+ * or renaming a code is MAJOR. Consumers SHOULD handle unknown codes gracefully.
+ *
+ * @public
+ */
+export type FindingCode = 'envelope-invalid' | 'envelope-adherence' | 'schema-invalid' | 'name-consistency' | 'mcp-key-sync' | 'marketplace-registration' | 'freshness';
+/**
+ * A single validation finding.
+ *
+ * @public
+ */
+export interface Finding {
+    severity: 'hard' | 'soft';
+    code: FindingCode;
+    /** Plugin name, if the finding is scoped to a specific plugin. */
+    plugin?: string;
+    /** Human-readable message. */
+    message: string;
+    /** Optional remediation hint. */
+    hint?: string;
+}
+/**
+ * Options for {@link scaffold}.
+ *
+ * @public
+ */
+export interface ScaffoldOptions {
+    /** Targets to scaffold for. Defaults to all known targets. */
+    targets?: readonly TargetId[];
+    /** Description field for the generated plugin. */
+    description?: string;
+}
+/**
+ * Options for {@link init}.
+ *
+ * @public
+ */
+export interface InitOptions {
+    /**
+     * Repo name written into the generated `package.json`. Defaults to the basename of the target
+     * directory.
+     */
+    name?: string;
+}
+/**
+ * Options for {@link migrate}.
+ *
+ * @public
+ */
+export interface MigrateOptions {
+    /** When true, print planned changes without writing. Default: false. */
+    dryRun?: boolean;
+}
+/**
+ * Result of running {@link migrate}.
+ *
+ * @public
+ */
+export interface MigrateResult {
+    /**
+     * Discriminant so consumers distinguish "ran and did nothing" from "ran and applied zero
+     * of N" from "ran and failed." Retrofitting this later would be breaking.
+     */
+    status: 'no-migrations-needed' | 'applied' | 'failed';
+    /** 0 in v0.1.0. */
+    migrationsApplied: number;
+    /** Absolute paths of files modified. */
+    filesChanged: string[];
+}
+/**
+ * Diagnostic report from {@link checkSupport} describing a plugin's support envelope.
+ *
+ * @public
+ */
+export interface SupportReport {
+    plugin: string;
+    /** Targets the plugin declares support for. */
+    declared: TargetId[];
+    /** Declared targets that are missing required artifacts. */
+    missingArtifacts: {
+        target: TargetId;
+        missing: string[];
+    }[];
+    /** Targets not declared but plausibly addable, with the files the author would need. */
+    suggestions: {
+        target: TargetId;
+        wouldNeed: string[];
+    }[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/pipeline/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE1E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,2DAMiB,CAAC;AAmBzC;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,MAAM,EAAE,QAAQ,CAAC;CAClB;AAKD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB,kBAAkB,GAClB,oBAAoB,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,cAAc,GACd,0BAA0B,GAC1B,WAAW,CAAC;AAEhB;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAKD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC9B,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAKD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,MAAM,EAAE,sBAAsB,GAAG,SAAS,GAAG,QAAQ,CAAC;IACtD,mBAAmB;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAKD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,4DAA4D;IAC5D,gBAAgB,EAAE;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC5D,wFAAwF;IACxF,WAAW,EAAE;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CAC1D"}

package/dist/pipeline/types.js

@@ -0,0 +1,26 @@
+/**
+ * Public types for the core API. These are the contract surface per §8.1 of the spec.
+ */
+/**
+ * Canonical list of target IDs known to this toolkit version. Runtime-exposed so
+ * `listTargets()` and config validation share one source of truth.
+ *
+ * `as const satisfies readonly TargetId[]` preserves the literal tuple type (required by
+ * `z.enum`) while guaranteeing every entry is a valid {@link TargetId}. The
+ * `_targetIdsAreExhaustive` assertion below closes the other direction (every {@link TargetId}
+ * appears here), so the union and the array cannot drift in either direction.
+ *
+ * Not part of the public API — `index.ts` re-exports only the `TargetId` type, not this runtime
+ * array. Marked `@internal` so the release-tag lint rule is satisfied without widening the
+ * public surface.
+ *
+ * @internal
+ */
+export const TARGET_IDS = [
+    'claude',
+    'cursor',
+    'gemini',
+    'kiro',
+    'vercel',
+];
+//# sourceMappingURL=types.js.map

package/dist/pipeline/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,QAAQ;CAC8B,CAAC"}

package/dist/pipeline/validate.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Cross-target validator for the pipeline layer.
+ *
+ * Implements §10.1 steps 1, 3, 4, and most of 5 (freshness deferred to Stage 5).
+ * Step 2 (per-target schema validation) lives in each target's own validate.ts and is
+ * not invoked here — this module is concerned only with cross-target consistency.
+ *
+ * @see docs/specs/architecture.md §6, §8.1, §10.1, §10.2
+ */
+import type { Finding, TargetId, ValidateOptions, ValidationResult } from './types.js';
+/**
+ * Minimum required artifacts for each target. Missing any of these when the target is
+ * in the envelope is an adherence violation.
+ * Vercel requires at least one skills/<name>/SKILL.md — handled specially below.
+ */
+export declare const TARGET_MIN_REQUIRED: Record<TargetId, string[]>;
+/**
+ * Validate an already-loaded `aipm.config.ts` value against AipmConfig's Zod schema.
+ * Loading from disk is the pipeline orchestrator's job (Stage 5). Here we only validate shape.
+ * Emits `envelope-invalid` findings on malformed input.
+ *
+ * `pluginName` is used to populate Finding.plugin.
+ */
+export declare function validateEnvelopeShape(rawConfig: unknown, pluginName: string): Finding[];
+/**
+ * For each target in the envelope: verify the plugin provides the minimum required artifacts.
+ * For each target NOT in the envelope: verify no target-specific artifacts exist for it.
+ *
+ * Emits `envelope-adherence` findings.
+ */
+export declare function validateEnvelopeAdherence(pluginDir: string, envelope: readonly TargetId[]): Finding[];
+/**
+ * Check that the plugin directory name matches the `name` field in every declared target's
+ * manifest. Reads each manifest and parses its `name` field (doesn't re-run the full schema —
+ * just extracts name).
+ *
+ * Emits `name-consistency` findings, one per mismatched manifest.
+ */
+export declare function validateNameConsistency(pluginDir: string, envelope: readonly TargetId[]): Finding[];
+/**
+ * When both Claude/Cursor (.mcp.json) and Kiro (mcp.json) are in the envelope, the set of
+ * mcpServers keys must match between them. Skip the check if fewer than two MCP-consuming
+ * targets are in the envelope.
+ *
+ * Emits `mcp-key-sync` findings.
+ */
+export declare function validateMcpKeySync(pluginDir: string, envelope: readonly TargetId[]): Finding[];
+/**
+ * Verify the plugin is listed in the appropriate template-level marketplace.json files.
+ *
+ * - If `claude` is in the envelope, the plugin MUST appear in `<repoRoot>/.claude-plugin/marketplace.json`'s
+ *   plugins array with name matching directory basename and source pointing at `./plugins/<name>`.
+ * - If `cursor` is in the envelope, same check against `<repoRoot>/.cursor-plugin/marketplace.json`.
+ * - If a target is NOT in the envelope, the plugin MUST NOT be listed in that marketplace.
+ *
+ * Emits `marketplace-registration` findings.
+ */
+export declare function validateMarketplaceRegistration(pluginDir: string, repoRoot: string, envelope: readonly TargetId[]): Finding[];
+/**
+ * Convenience: run all cross-target validators for a single plugin and combine findings.
+ * Stage 5's pipeline operations.ts uses this.
+ *
+ * Note: validateEnvelopeShape is excluded here because the caller must already have a
+ * parsed envelope (TargetId[]) — meaning shape validation already passed. Shape validation
+ * must be done separately before calling this function.
+ */
+export declare function validateCrossTarget(pluginDir: string, repoRoot: string, envelope: readonly TargetId[]): Finding[];
+/**
+ * Validate one plugin or every plugin under a repo root (§5.3). Runs the validators in the order
+ * mandated by §10.1 / §10.3:
+ *
+ *   1. Envelope load + shape validation. A load/shape failure emits `envelope-invalid` and
+ *      **skips all further checks for that plugin** (no point validating an undeclared target).
+ *   2. Per-target schema validation (each declared target's `validate.ts`). Schema errors
+ *      **block cross-target checks** for that plugin (§10.3).
+ *   3. Envelope adherence.
+ *   4. Cross-target consistency (only when the envelope has more than one target and no blocking
+ *      schema errors): name consistency, MCP key sync, marketplace registration.
+ *   5. Freshness (unless `opts.skipFreshness`). Severity is `hard` in CI, `soft` locally (§10.2).
+ *
+ * `passed` is `true` iff no **hard** findings were emitted (§10.2).
+ *
+ * @param targetPath - Absolute path to a single plugin directory or a repo root.
+ * @param opts - Validate options. `ci` controls freshness severity (default: local/soft).
+ * @returns The combined validation result.
+ */
+export declare function runValidate(targetPath: string, opts?: ValidateOptions & {
+    ci?: boolean;
+}): Promise<ValidationResult>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/pipeline/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/pipeline/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqBH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAgCvF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,CAM1D,CAAC;AA4DF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,EAAE,CAsBvF;AAMD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CA4FX;AAMD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CAkFX;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,EAAE,CAgD9F;AAMD;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CAqGX;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CAOX;AA+KD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,eAAe,GAAG;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,GACxC,OAAO,CAAC,gBAAgB,CAAC,CAwD3B"}