@ai-plugin-marketplace/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike North
+
+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,67 @@
+# @ai-plugin-marketplace/core
+
+Build pipeline, validation, scaffolding, and `defineConfig` — the programmatic API behind the
+`aipm` CLI.
+
+> Most users should install [`@ai-plugin-marketplace/cli`](../cli) instead. Use this package
+> directly only when you need to call the build/validate operations from your own scripts.
+
+## Install
+
+```sh
+pnpm add -D @ai-plugin-marketplace/core
+```
+
+## Public API
+
+All exports are available from the root import path — there are no public subpaths.
+
+```ts
+import {
+  defineConfig,
+  build,
+  validate,
+  scaffold,
+  init,
+  migrate,
+  checkSupport,
+  addTarget,
+  listTargets,
+} from '@ai-plugin-marketplace/core';
+```
+
+### Config
+
+| Export            | Description                                                              |
+| ----------------- | ------------------------------------------------------------------------ |
+| `defineConfig`    | Validates and brands an `AipmConfigInput`; use in every `aipm.config.ts` |
+| `AipmConfigInput` | Input type: `{ version: string; targets: TargetId[] }`                   |
+| `AipmConfig`      | Branded output type returned by `defineConfig`                           |
+
+### Operations
+
+| Export         | Description                                                        |
+| -------------- | ------------------------------------------------------------------ |
+| `init`         | Scaffold a new plugin repo at a given directory                    |
+| `build`        | Build artifacts for a plugin or all plugins under a repo root      |
+| `validate`     | Inspect on-disk state and return `ValidationResult` (read-only)    |
+| `scaffold`     | Create a new plugin directory from templates                       |
+| `migrate`      | Apply schema migrations (no-op in v0.1.0; real in future releases) |
+| `checkSupport` | Report missing artifacts and expansion suggestions for a plugin    |
+| `addTarget`    | Scaffold skeleton files for a new target in an existing plugin     |
+| `listTargets`  | Return the `TargetId` values this toolkit version recognises       |
+
+### Key types
+
+`TargetId`, `BuildOptions`, `BuildResult`, `GeneratedFile`, `ValidateOptions`,
+`ValidationResult`, `Finding`, `FindingCode`, `ScaffoldOptions`, `InitOptions`,
+`MigrateOptions`, `MigrateResult`, `SupportReport`.
+
+## Links
+
+- [Architecture spec](../../docs/specs/architecture.md) (§8.1 for the full public-API contract)
+- [Repository](https://github.com/ai-plugin-marketplace/tools)
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Plugin author configuration — `aipm.config.ts`.
+ *
+ * Per §6.1 of the architecture spec, `defineConfig` takes an `AipmConfigInput` and returns a
+ * branded `AipmConfig`. The brand symbol is module-private (never exported); consumers see
+ * `AipmConfig` as `AipmConfigInput` plus a structural marker proving `defineConfig` validated
+ * the value.
+ */
+import type { TargetId } from './pipeline/types.js';
+/**
+ * Raw input shape accepted by `defineConfig`. Plugin authors type their config literal against
+ * `AipmConfigInput` implicitly via `defineConfig`'s parameter.
+ *
+ * @public
+ */
+export interface AipmConfigInput {
+    /** Semver string identifying the plugin author's release. See §9.5 of the spec. */
+    version: string;
+    /** Targets this plugin supports. See §6 of the spec. */
+    targets: readonly TargetId[];
+}
+/**
+ * Module-private brand marker. Intentionally never exported (§8.1: "The brand symbol is
+ * module-private"). Marked `@internal` so API Extractor does not flag `AipmConfig`'s reference
+ * to it as `ae-forgotten-export`; the symbol carries no runtime value and does not appear in the
+ * trimmed public rollup.
+ *
+ * @internal
+ */
+declare const aipmConfigBrand: unique symbol;
+/**
+ * Validated plugin configuration. Structurally identical to `AipmConfigInput` but carries a
+ * module-private brand indicating `defineConfig` validated it at runtime.
+ *
+ * @public
+ */
+export type AipmConfig = AipmConfigInput & {
+    readonly [aipmConfigBrand]: 'AipmConfig';
+};
+/**
+ * Validate and brand a plugin configuration. Throws a `ZodError` on invalid input.
+ *
+ * @public
+ */
+export declare function defineConfig(config: AipmConfigInput): AipmConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,OAAO,CAAC,MAAM,eAAe,EAAE,OAAO,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG;IACzC,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,YAAY,CAAC;CAC1C,CAAC;AAqBF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAKhE"}

package/dist/config.js

@@ -0,0 +1,38 @@
+/**
+ * Plugin author configuration — `aipm.config.ts`.
+ *
+ * Per §6.1 of the architecture spec, `defineConfig` takes an `AipmConfigInput` and returns a
+ * branded `AipmConfig`. The brand symbol is module-private (never exported); consumers see
+ * `AipmConfig` as `AipmConfigInput` plus a structural marker proving `defineConfig` validated
+ * the value.
+ */
+import { z } from 'zod';
+import { TARGET_IDS } from './pipeline/types.js';
+/**
+ * Zod schema used for runtime validation. Uses `.strict()` to reject unknown keys.
+ *
+ * `version` must parse as semver. `targets` must be a non-empty subset of known target IDs and
+ * must not contain duplicates.
+ */
+const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const aipmConfigSchema = z
+    .object({
+    version: z.string().regex(semverPattern, 'version must be a valid semver string'),
+    targets: z
+        .array(z.enum(TARGET_IDS))
+        .min(1, 'targets must contain at least one target')
+        .refine((arr) => new Set(arr).size === arr.length, 'targets must not contain duplicates'),
+})
+    .strict();
+/**
+ * Validate and brand a plugin configuration. Throws a `ZodError` on invalid input.
+ *
+ * @public
+ */
+export function defineConfig(config) {
+    const parsed = aipmConfigSchema.parse(config);
+    // Brand injection: the parsed value is structurally AipmConfigInput; the brand is a
+    // type-only marker proving validation ran. Cast through `unknown` per TS guidance.
+    return parsed;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAmCjD;;;;;GAKG;AACH,MAAM,aAAa,GACjB,qFAAqF,CAAC;AAExF,MAAM,gBAAgB,GAAG,CAAC;KACvB,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,aAAa,EAAE,uCAAuC,CAAC;IACjF,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;SACzB,GAAG,CAAC,CAAC,EAAE,0CAA0C,CAAC;SAClD,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,EAAE,qCAAqC,CAAC;CAC5F,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB;IAClD,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9C,oFAAoF;IACpF,mFAAmF;IACnF,OAAO,MAA+B,CAAC;AACzC,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,291 @@
+/**
+ * `@ai-plugin-marketplace/core` — public API.
+ *
+ * Only the exports listed here are part of the public contract. Per §8.1 of the architecture
+ * spec (`docs/specs/architecture.md`), the package's only public subpath is the root — types
+ * and functions import from `@ai-plugin-marketplace/core` directly, not from `/types`,
+ * `/config`, `/targets`, or any internal subpath.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Scaffold skeleton files for a new target in an existing plugin (§6.4).
+ *
+ * @public
+ */
+export declare function addTarget(pluginDir: string, target: TargetId): Promise<void>;
+
+/**
+ * Validated plugin configuration. Structurally identical to `AipmConfigInput` but carries a
+ * module-private brand indicating `defineConfig` validated it at runtime.
+ *
+ * @public
+ */
+export declare type AipmConfig = AipmConfigInput & {
+    readonly [aipmConfigBrand]: 'AipmConfig';
+};
+
+/**
+ * Module-private brand marker. Intentionally never exported (§8.1: "The brand symbol is
+ * module-private"). Marked `@internal` so API Extractor does not flag `AipmConfig`'s reference
+ * to it as `ae-forgotten-export`; the symbol carries no runtime value and does not appear in the
+ * trimmed public rollup.
+ *
+ * @internal
+ */
+declare const aipmConfigBrand: unique symbol;
+
+/**
+ * Raw input shape accepted by `defineConfig`. Plugin authors type their config literal against
+ * `AipmConfigInput` implicitly via `defineConfig`'s parameter.
+ *
+ * @public
+ */
+export declare interface AipmConfigInput {
+    /** Semver string identifying the plugin author's release. See §9.5 of the spec. */
+    version: string;
+    /** Targets this plugin supports. See §6 of the spec. */
+    targets: readonly TargetId[];
+}
+
+/**
+ * Build a single plugin or every plugin under a repo root. `path` may be a plugin directory
+ * (contains `aipm.config.ts`) or a repo root (contains `plugins/`); the orchestrator detects
+ * which and returns a length-1 array for single-plugin input. See §5.2, §8.1.
+ *
+ * @public
+ */
+export declare function build(targetPath: string, opts?: BuildOptions): Promise<BuildResult[]>;
+
+/**
+ * Options for {@link build}.
+ *
+ * @public
+ */
+export declare 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 declare 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;
+}
+
+/**
+ * Diagnose a plugin's support envelope: declared targets, missing artifacts, addable targets (§6.4).
+ *
+ * @public
+ */
+export declare function checkSupport(pluginDir: string): Promise<SupportReport>;
+
+/**
+ * Validate and brand a plugin configuration. Throws a `ZodError` on invalid input.
+ *
+ * @public
+ */
+export declare function defineConfig(config: AipmConfigInput): AipmConfig;
+
+/**
+ * A single validation finding.
+ *
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * 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 declare type FindingCode = 'envelope-invalid' | 'envelope-adherence' | 'schema-invalid' | 'name-consistency' | 'mcp-key-sync' | 'marketplace-registration' | 'freshness';
+
+/**
+ * A file produced or verified by the build.
+ *
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * Scaffold a thin consumer repo (the "template") at `targetDir` that depends on
+ * `@ai-plugin-marketplace/cli` and holds plugin sources only (§3.2, §11). The generated
+ * `package.json` pins the cli dev dependency to a caret of the current toolkit version (§9.1
+ * lockstep). Refuses to write into a non-empty directory.
+ *
+ * @public
+ */
+export declare function init(targetDir: string, opts?: InitOptions): Promise<void>;
+
+/**
+ * Options for {@link init}.
+ *
+ * @public
+ */
+export declare interface InitOptions {
+    /**
+     * Repo name written into the generated `package.json`. Defaults to the basename of the target
+     * directory.
+     */
+    name?: string;
+}
+
+/**
+ * List the target IDs this toolkit version knows about (§6.4).
+ *
+ * @public
+ */
+export declare function listTargets(): readonly TargetId[];
+
+/**
+ * No-op in v0.1.0 per §8.1 of the spec. Always returns `status: 'no-migrations-needed'` because
+ * §9.4 constrains every `schemaVersion` to a single value. When real migrations ship, this
+ * must distinguish up-to-date from unknown-future-version.
+ *
+ * @public
+ */
+export declare function migrate(_path: string, _opts?: MigrateOptions): Promise<MigrateResult>;
+
+/**
+ * Options for {@link migrate}.
+ *
+ * @public
+ */
+export declare interface MigrateOptions {
+    /** When true, print planned changes without writing. Default: false. */
+    dryRun?: boolean;
+}
+
+/**
+ * Result of running {@link migrate}.
+ *
+ * @public
+ */
+export declare 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[];
+}
+
+/**
+ * Scaffold a new plugin under `<cwd>/plugins/<name>`. The plugins directory is derived from the
+ * current working directory, matching how `aipm scaffold` is invoked from a template repo root.
+ *
+ * @public
+ */
+export declare function scaffold(name: string, opts?: ScaffoldOptions): Promise<void>;
+
+/**
+ * Options for {@link scaffold}.
+ *
+ * @public
+ */
+export declare interface ScaffoldOptions {
+    /** Targets to scaffold for. Defaults to all known targets. */
+    targets?: readonly TargetId[];
+    /** Description field for the generated plugin. */
+    description?: string;
+}
+
+/**
+ * Diagnostic report from {@link checkSupport} describing a plugin's support envelope.
+ *
+ * @public
+ */
+export declare 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[];
+    }[];
+}
+
+/**
+ * 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 declare type TargetId = 'claude' | 'cursor' | 'gemini' | 'kiro' | 'vercel';
+
+/**
+ * Validate a single plugin or every plugin under a repo root, in the order defined by §10.1.
+ * Freshness severity follows the CI environment (§10.2).
+ *
+ * @public
+ */
+export declare function validate(targetPath: string, opts?: ValidateOptions): Promise<ValidationResult>;
+
+/**
+ * Options for {@link validate}.
+ *
+ * @public
+ */
+export declare interface ValidateOptions {
+    /** When true, skip the freshness check (§10.5). Default: false. */
+    skipFreshness?: boolean;
+}
+
+/**
+ * Result of validating one or more plugins.
+ *
+ * @public
+ */
+export declare interface ValidationResult {
+    findings: Finding[];
+    /** True iff no hard findings were emitted. Soft findings do not flip this. */
+    passed: boolean;
+}
+
+export { }

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@ai-plugin-marketplace/core` — public API.
+ *
+ * Only the exports listed here are part of the public contract. Per §8.1 of the architecture
+ * spec (`docs/specs/architecture.md`), the package's only public subpath is the root — types
+ * and functions import from `@ai-plugin-marketplace/core` directly, not from `/types`,
+ * `/config`, `/targets`, or any internal subpath.
+ *
+ * @packageDocumentation
+ */
+export { defineConfig } from './config.js';
+export type { AipmConfig, AipmConfigInput } from './config.js';
+export { build, validate, scaffold, init, migrate, checkSupport, addTarget, listTargets, } from './pipeline/operations.js';
+export type { TargetId, BuildOptions, BuildResult, GeneratedFile, ValidateOptions, ValidationResult, Finding, FindingCode, ScaffoldOptions, InitOptions, MigrateOptions, MigrateResult, SupportReport, } from './pipeline/types.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;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EACL,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,YAAY,EACZ,SAAS,EACT,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EACb,aAAa,GACd,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@ai-plugin-marketplace/core` — public API.
+ *
+ * Only the exports listed here are part of the public contract. Per §8.1 of the architecture
+ * spec (`docs/specs/architecture.md`), the package's only public subpath is the root — types
+ * and functions import from `@ai-plugin-marketplace/core` directly, not from `/types`,
+ * `/config`, `/targets`, or any internal subpath.
+ *
+ * @packageDocumentation
+ */
+export { defineConfig } from './config.js';
+export { build, validate, scaffold, init, migrate, checkSupport, addTarget, listTargets, } from './pipeline/operations.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EACL,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,YAAY,EACZ,SAAS,EACT,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/pipeline/build.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Build orchestrator (§5.2).
+ *
+ * `runBuild` loads each plugin's envelope, dispatches to the per-target build steps, writes the
+ * generated artifacts, and (per §5.4) runs validation before returning. The pipeline holds no
+ * target-specific transformation logic — it dispatches to the per-target internal modules under
+ * `targets/<id>/` (§7.2). Cross-target imports between `targets/<X>` and `targets/<Y>` are
+ * forbidden, but the pipeline is permitted to orchestrate all of them.
+ *
+ * **Sentinel scope (§4.3).** Only the in-plugin-dir generated hook JSONs (`hooks/claude.json`,
+ * `hooks/hooks.json`) carry a `_generated` JSON sentinel. The `dist/**` bundle trees are
+ * wholly-generated and stay sentinel-less so they remain byte-identical to the committed
+ * template oracle; freshness for those is a whole-tree regeneration compare (§10.5).
+ *
+ * @see docs/specs/architecture.md §5.2 (build phase), §5.4 (phase invariants), §7.2, §10.5
+ */
+import type { SentinelMode } from './sentinel.js';
+import type { BuildOptions, BuildResult, TargetId } from './types.js';
+/**
+ * A toolkit-generated file that lives **inside the plugin directory** and carries a sentinel.
+ * Both the build (which writes `expectedContent`) and the freshness check (which compares the
+ * on-disk bytes against `expectedContent`) derive these from one place so they cannot diverge.
+ */
+export interface PluginHookArtifact {
+    /** Absolute path of the generated file. */
+    absPath: string;
+    /** Author-authored source path, relative to the plugin dir (recorded in the sentinel). */
+    source: string;
+    /** Sentinel carrier used for this artifact. */
+    sentinelMode: SentinelMode;
+    /** Which target's build step produced this file. */
+    target: TargetId;
+    /** Exact bytes the build writes (sentinel included). */
+    expectedContent: string;
+}
+/**
+ * Compute every in-plugin-dir generated hook JSON for a plugin given its envelope, **without
+ * writing**. This is the single source of truth shared by `runBuild` and the freshness check.
+ *
+ * - `claude` in envelope + a hooks YAML present → `hooks/claude.json` (Claude JSON + sentinel).
+ * - `gemini` in envelope + a hooks YAML present → `hooks/hooks.json` (Gemini JSON + sentinel).
+ *
+ * The sentinel is applied to the **parsed object** so the on-disk file carries a top-level
+ * `_generated` field (§4.3), serialized 2-space + trailing newline.
+ *
+ * @throws {Error} If the hooks YAML is malformed or fails the Claude hooks schema.
+ */
+export declare function computePluginHookArtifacts(pluginDir: string, envelope: readonly TargetId[]): PluginHookArtifact[];
+/**
+ * The set of `dist/**` bundle trees a plugin's envelope produces. Each entry names the absolute
+ * destination directory and a `regenerate` closure that rebuilds the tree into an arbitrary
+ * directory — used both to emit the real bundle (build) and to regenerate into a temp dir for
+ * the byte-parity freshness compare (§10.5). Bundles are sentinel-less by design.
+ */
+export interface DistBundle {
+    target: TargetId;
+    /** Absolute destination directory under `dist/`. */
+    destDir: string;
+    /** Rebuild the bundle into `into` (clears `into` first, per the bundlers' contract). */
+    regenerate: (into: string) => void;
+}
+/**
+ * Compute the `dist/**` bundles a plugin's envelope produces, **without writing**. Shared by
+ * build (calls `regenerate(destDir)`) and freshness (calls `regenerate(tempDir)` then compares).
+ */
+export declare function computeDistBundles(pluginDir: string, distDir: string, envelope: readonly TargetId[]): DistBundle[];
+/** Collect every file path under `dir`, relative to `dir`. Returns `[]` if `dir` is absent. */
+export declare function collectFilesRelative(dir: string): string[];
+/**
+ * Build one plugin or every plugin under a repo root (§8.1). `targetPath` is detected as a single
+ * plugin directory (contains `aipm.config.ts`) or a repo root (contains a `plugins/` directory).
+ *
+ * After emitting artifacts, runs `runValidate(targetPath, { skipFreshness: true })` per §5.4. When
+ * `opts.failFast` is set and validation reports hard findings, throws an Error summarizing them;
+ * otherwise the build results are returned and the caller (CLI) decides the exit code.
+ *
+ * @param targetPath - Absolute path to a plugin directory or repo root.
+ * @param opts - Build options.
+ * @returns One `BuildResult` per built plugin (length-1 for single-plugin input).
+ * @throws {Error} If `targetPath` is neither a plugin nor a repo root, a config fails to load,
+ *   a transform fails, or (when `failFast`) post-build validation reports hard findings.
+ */
+export declare function runBuild(targetPath: string, opts?: BuildOptions): Promise<BuildResult[]>;
+/**
+ * Regenerate a dist bundle into a fresh temp directory and return that directory. The caller is
+ * responsible for removing it. Used by the freshness check (§10.5) to byte-compare against the
+ * on-disk bundle without disturbing it.
+ */
+export declare function regenerateBundleToTemp(bundle: DistBundle): string;
+//# sourceMappingURL=build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/pipeline/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAeH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAiB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMrF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,YAAY,EAAE,YAAY,CAAC;IAC3B,oDAAoD;IACpD,MAAM,EAAE,QAAQ,CAAC;IACjB,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;CACzB;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,kBAAkB,EAAE,CAoCtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,QAAQ,CAAC;IACjB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,UAAU,EAAE,CA0Bd;AAMD,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAa1D;AA6DD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAsB9F;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAIjE"}