@ai-plugin-marketplace/core 0.1.0 → 0.3.0

package/dist/config.d.ts

@@ -18,6 +18,18 @@ export interface AipmConfigInput {
     version: string;
     /** Targets this plugin supports. See §6 of the spec. */
     targets: readonly TargetId[];
+    /**
+     * Optional one-line description of the plugin. When the repo opts into registry generation (an
+     * `aipm.workspace.ts` is present), this becomes the plugin entry's `description` (Claude/Cursor)
+     * in the generated `marketplace.json`. Optional so existing configs stay valid.
+     */
+    description?: string;
+    /**
+     * Optional discovery keywords for the plugin. When the repo opts into registry generation, these
+     * become the plugin entry's `tags` (Claude/Cursor) in the generated `marketplace.json`. Optional
+     * so existing configs stay valid.
+     */
+    keywords?: readonly string[];
 }
 /**
  * Module-private brand marker. Intentionally never exported (§8.1: "The brand symbol is
@@ -43,5 +55,105 @@ export type AipmConfig = AipmConfigInput & {
  * @public
  */
 export declare function defineConfig(config: AipmConfigInput): AipmConfig;
+/**
+ * Raw input shape accepted by `defineRepoConfig`. Authored as `aipm.repo.ts` at the **repo
+ * root** of a project that hosts a marketplace inside a larger software repo. The file is
+ * optional: when absent, the toolkit behaves as if `defineRepoConfig({})` was used, reproducing
+ * the historical "repo root == marketplace root, fixed `plugins/`" topology.
+ *
+ * Both paths are repo-root-relative and must stay within the repo (no absolute paths, no `..`
+ * segments), because host platforms resolve a plugin's `source` relative to the repo root.
+ *
+ * @public
+ */
+export interface AipmRepoConfigInput {
+    /**
+     * Directory (relative to the repo root) that holds plugin folders. Relocate this when the host
+     * software already owns a top-level `plugins/` directory. Default: `'plugins'`.
+     */
+    pluginsRoot?: string;
+    /**
+     * Directory (relative to the repo root) for generated `dist/` bundles. Relocate this when the
+     * host software already owns a top-level `dist/`. Default: `'dist'`.
+     */
+    distDir?: string;
+}
+/**
+ * Module-private brand marker for {@link AipmRepoConfig}. Never exported.
+ *
+ * @internal
+ */
+declare const aipmRepoConfigBrand: unique symbol;
+/**
+ * Validated repo configuration. Carries a module-private brand indicating `defineRepoConfig`
+ * validated it; unlike the input, both fields are always present (defaults applied).
+ *
+ * @public
+ */
+export type AipmRepoConfig = {
+    readonly pluginsRoot: string;
+    readonly distDir: string;
+} & {
+    readonly [aipmRepoConfigBrand]: 'AipmRepoConfig';
+};
+/**
+ * Validate and brand a repo configuration, applying defaults for any omitted field. Throws a
+ * `ZodError` on invalid input (unknown keys, absolute paths, `..` escapes).
+ *
+ * @public
+ */
+export declare function defineRepoConfig(config?: AipmRepoConfigInput): AipmRepoConfig;
+/**
+ * Raw input shape accepted by `defineWorkspace`. Authored as `aipm.workspace.ts` at the **repo
+ * root**. Its presence opts the repo into **marketplace-registry generation**: the toolkit
+ * generates the per-target `marketplace.json` registries from this workspace metadata plus the
+ * discovered plugins, commits them, and freshness-checks them. When the file is **absent**, the
+ * toolkit behaves exactly as before (registries are hand-authored and `validateMarketplaceRegistration`
+ * runs).
+ *
+ * @public
+ */
+export interface AipmWorkspaceInput {
+    /** Marketplace-level metadata shared across all generated registries. */
+    marketplace: {
+        /** Marketplace name — the registry's top-level `name`. */
+        name: string;
+        /**
+         * Optional owner block written to the Claude/Cursor registries' top-level `owner`. The Codex
+         * registry has no owner concept, so this is ignored there.
+         */
+        owner?: {
+            name: string;
+            email?: string;
+        };
+        /**
+         * Optional marketplace description. For Claude/Cursor it becomes `metadata.description`; for
+         * Codex it is currently unused (the Codex registry has no marketplace-level description field).
+         */
+        description?: string;
+    };
+}
+/**
+ * Module-private brand marker for {@link AipmWorkspace}. Never exported.
+ *
+ * @internal
+ */
+declare const aipmWorkspaceBrand: unique symbol;
+/**
+ * Validated workspace configuration. Structurally identical to {@link AipmWorkspaceInput} but
+ * carries a module-private brand indicating `defineWorkspace` validated it at runtime.
+ *
+ * @public
+ */
+export type AipmWorkspace = AipmWorkspaceInput & {
+    readonly [aipmWorkspaceBrand]: 'AipmWorkspace';
+};
+/**
+ * Validate and brand a workspace configuration. Throws a `ZodError` on invalid input (unknown
+ * keys, missing `marketplace.name`).
+ *
+ * @public
+ */
+export declare function defineWorkspace(config: AipmWorkspaceInput): AipmWorkspace;
 export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,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;IAC7B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,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;AAuBF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAKhE;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,OAAO,CAAC,MAAM,mBAAmB,EAAE,OAAO,MAAM,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GAAG;IAAE,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAuBzD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,mBAAwB,GAAG,cAAc,CAGjF;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,WAAW,EAAE;QACX,0DAA0D;QAC1D,IAAI,EAAE,MAAM,CAAC;QACb;;;WAGG;QACH,KAAK,CAAC,EAAE;YACN,IAAI,EAAE,MAAM,CAAC;YACb,KAAK,CAAC,EAAE,MAAM,CAAC;SAChB,CAAC;QACF;;;WAGG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;GAIG;AACH,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG;IAC/C,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,eAAe,CAAC;CAChD,CAAC;AAoBF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa,CAGzE"}

package/dist/config.js

@@ -6,6 +6,7 @@
  * `AipmConfig` as `AipmConfigInput` plus a structural marker proving `defineConfig` validated
  * the value.
  */
+import * as path from 'node:path';
 import { z } from 'zod';
 import { TARGET_IDS } from './pipeline/types.js';
 /**
@@ -22,6 +23,8 @@ const aipmConfigSchema = 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'),
+    description: z.string().optional(),
+    keywords: z.array(z.string()).optional(),
 })
     .strict();
 /**
@@ -35,4 +38,57 @@ export function defineConfig(config) {
     // type-only marker proving validation ran. Cast through `unknown` per TS guidance.
     return parsed;
 }
+/**
+ * A repo-relative path that is safe to join onto the repo root: non-empty, not absolute, and
+ * containing no `..` segment that could escape the repo. Host platforms resolve plugin `source`
+ * paths relative to the repo root, so an escaping root would be unrepresentable.
+ */
+const repoRelativePath = z
+    .string()
+    .min(1, 'path must not be empty')
+    .refine((p) => !path.isAbsolute(p), 'path must be relative to the repo root, not absolute')
+    .refine((p) => !p.split(/[\\/]/).includes('..'), "path must not contain a '..' segment (it must stay within the repo root)");
+const aipmRepoConfigSchema = z
+    .object({
+    pluginsRoot: repoRelativePath.default('plugins'),
+    distDir: repoRelativePath.default('dist'),
+})
+    .strict();
+/**
+ * Validate and brand a repo configuration, applying defaults for any omitted field. Throws a
+ * `ZodError` on invalid input (unknown keys, absolute paths, `..` escapes).
+ *
+ * @public
+ */
+export function defineRepoConfig(config = {}) {
+    const parsed = aipmRepoConfigSchema.parse(config);
+    return parsed;
+}
+const aipmWorkspaceSchema = z
+    .object({
+    marketplace: z
+        .object({
+        name: z.string().min(1, 'marketplace.name must not be empty'),
+        owner: z
+            .object({
+            name: z.string().min(1, 'marketplace.owner.name must not be empty'),
+            email: z.string().optional(),
+        })
+            .strict()
+            .optional(),
+        description: z.string().optional(),
+    })
+        .strict(),
+})
+    .strict();
+/**
+ * Validate and brand a workspace configuration. Throws a `ZodError` on invalid input (unknown
+ * keys, missing `marketplace.name`).
+ *
+ * @public
+ */
+export function defineWorkspace(config) {
+    const parsed = aipmWorkspaceSchema.parse(config);
+    return parsed;
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/core.d.ts

@@ -47,6 +47,110 @@ export declare interface AipmConfigInput {
     version: string;
     /** Targets this plugin supports. See §6 of the spec. */
     targets: readonly TargetId[];
+    /**
+     * Optional one-line description of the plugin. When the repo opts into registry generation (an
+     * `aipm.workspace.ts` is present), this becomes the plugin entry's `description` (Claude/Cursor)
+     * in the generated `marketplace.json`. Optional so existing configs stay valid.
+     */
+    description?: string;
+    /**
+     * Optional discovery keywords for the plugin. When the repo opts into registry generation, these
+     * become the plugin entry's `tags` (Claude/Cursor) in the generated `marketplace.json`. Optional
+     * so existing configs stay valid.
+     */
+    keywords?: readonly string[];
+}
+
+/**
+ * Validated repo configuration. Carries a module-private brand indicating `defineRepoConfig`
+ * validated it; unlike the input, both fields are always present (defaults applied).
+ *
+ * @public
+ */
+export declare type AipmRepoConfig = {
+    readonly pluginsRoot: string;
+    readonly distDir: string;
+} & {
+    readonly [aipmRepoConfigBrand]: 'AipmRepoConfig';
+};
+
+/**
+ * Module-private brand marker for {@link AipmRepoConfig}. Never exported.
+ *
+ * @internal
+ */
+declare const aipmRepoConfigBrand: unique symbol;
+
+/**
+ * Raw input shape accepted by `defineRepoConfig`. Authored as `aipm.repo.ts` at the **repo
+ * root** of a project that hosts a marketplace inside a larger software repo. The file is
+ * optional: when absent, the toolkit behaves as if `defineRepoConfig({})` was used, reproducing
+ * the historical "repo root == marketplace root, fixed `plugins/`" topology.
+ *
+ * Both paths are repo-root-relative and must stay within the repo (no absolute paths, no `..`
+ * segments), because host platforms resolve a plugin's `source` relative to the repo root.
+ *
+ * @public
+ */
+export declare interface AipmRepoConfigInput {
+    /**
+     * Directory (relative to the repo root) that holds plugin folders. Relocate this when the host
+     * software already owns a top-level `plugins/` directory. Default: `'plugins'`.
+     */
+    pluginsRoot?: string;
+    /**
+     * Directory (relative to the repo root) for generated `dist/` bundles. Relocate this when the
+     * host software already owns a top-level `dist/`. Default: `'dist'`.
+     */
+    distDir?: string;
+}
+
+/**
+ * Validated workspace configuration. Structurally identical to {@link AipmWorkspaceInput} but
+ * carries a module-private brand indicating `defineWorkspace` validated it at runtime.
+ *
+ * @public
+ */
+export declare type AipmWorkspace = AipmWorkspaceInput & {
+    readonly [aipmWorkspaceBrand]: 'AipmWorkspace';
+};
+
+/**
+ * Module-private brand marker for {@link AipmWorkspace}. Never exported.
+ *
+ * @internal
+ */
+declare const aipmWorkspaceBrand: unique symbol;
+
+/**
+ * Raw input shape accepted by `defineWorkspace`. Authored as `aipm.workspace.ts` at the **repo
+ * root**. Its presence opts the repo into **marketplace-registry generation**: the toolkit
+ * generates the per-target `marketplace.json` registries from this workspace metadata plus the
+ * discovered plugins, commits them, and freshness-checks them. When the file is **absent**, the
+ * toolkit behaves exactly as before (registries are hand-authored and `validateMarketplaceRegistration`
+ * runs).
+ *
+ * @public
+ */
+export declare interface AipmWorkspaceInput {
+    /** Marketplace-level metadata shared across all generated registries. */
+    marketplace: {
+        /** Marketplace name — the registry's top-level `name`. */
+        name: string;
+        /**
+         * Optional owner block written to the Claude/Cursor registries' top-level `owner`. The Codex
+         * registry has no owner concept, so this is ignored there.
+         */
+        owner?: {
+            name: string;
+            email?: string;
+        };
+        /**
+         * Optional marketplace description. For Claude/Cursor it becomes `metadata.description`; for
+         * Codex it is currently unused (the Codex registry has no marketplace-level description field).
+         */
+        description?: string;
+    };
 }
 
 /**
@@ -98,6 +202,22 @@ export declare function checkSupport(pluginDir: string): Promise<SupportReport>;
  */
 export declare function defineConfig(config: AipmConfigInput): AipmConfig;
 
+/**
+ * Validate and brand a repo configuration, applying defaults for any omitted field. Throws a
+ * `ZodError` on invalid input (unknown keys, absolute paths, `..` escapes).
+ *
+ * @public
+ */
+export declare function defineRepoConfig(config?: AipmRepoConfigInput): AipmRepoConfig;
+
+/**
+ * Validate and brand a workspace configuration. Throws a `ZodError` on invalid input (unknown
+ * keys, missing `marketplace.name`).
+ *
+ * @public
+ */
+export declare function defineWorkspace(config: AipmWorkspaceInput): AipmWorkspace;
+
 /**
  * A single validation finding.
  *
@@ -118,9 +238,19 @@ export declare interface Finding {
  * Enumerated finding codes. Additive — new codes arrive in toolkit MINOR releases; removing
  * or renaming a code is MAJOR. Consumers SHOULD handle unknown codes gracefully.
  *
+ * `single-artifact-host` — a "single-artifact host" (`gemini` or `kiro`), which installs ONE
+ * extension/power per repo from the repo ROOT and has no marketplace concept, is declared by MORE
+ * THAN ONE plugin in the repo. The root artifact for that host is NOT emitted while the ambiguity
+ * stands (the toolkit can't choose which plugin owns the single root slot).
+ *
+ * `root-artifact-collision` — a generated repo-root path the toolkit would write is already
+ * occupied by a file the toolkit does NOT track as previously-generated (i.e. it belongs to the
+ * host software / the author). Generation refuses to overwrite it rather than clobber repo-root
+ * state.
+ *
  * @public
  */
-export declare type FindingCode = 'envelope-invalid' | 'envelope-adherence' | 'schema-invalid' | 'name-consistency' | 'mcp-key-sync' | 'marketplace-registration' | 'freshness';
+export declare type FindingCode = 'envelope-invalid' | 'repo-config-invalid' | 'envelope-adherence' | 'schema-invalid' | 'name-consistency' | 'mcp-key-sync' | 'marketplace-registration' | 'freshness' | 'single-artifact-host' | 'root-artifact-collision';
 
 /**
  * A file produced or verified by the build.
@@ -157,6 +287,13 @@ export declare interface InitOptions {
      * directory.
      */
     name?: string;
+    /**
+     * Version of `@ai-plugin-marketplace/cli` to pin the generated `package.json`'s `cli`
+     * dev dependency to (as `^<cliVersion>`). The cli entrypoint supplies its own version here; cli
+     * and core ship independently and may differ (e.g. `cli 0.1.1` ships with `core 0.2.0`). When
+     * omitted, falls back to core's own version (the historical lockstep assumption).
+     */
+    cliVersion?: string;
 }
 
 /**
@@ -203,8 +340,54 @@ export declare interface MigrateResult {
 }
 
 /**
- * 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.
+ * Options for {@link refreshScaffold}.
+ *
+ * @public
+ */
+export declare interface RefreshOptions {
+    /**
+     * Overwrite toolkit-owned scaffold files even when their on-disk content has diverged from what
+     * the toolkit last wrote (i.e. the user edited them). Without this, diverged files are reported
+     * as conflicts and left untouched.
+     */
+    force?: boolean;
+}
+
+/**
+ * Per-file outcome of a {@link refreshScaffold} run. Returned (one per managed scaffold file) so
+ * the CLI can report what changed without re-deriving it.
+ *
+ * @public
+ */
+export declare interface RefreshOutcome {
+    /** Repo-relative POSIX path of the managed scaffold file. */
+    path: string;
+    /**
+     * - `updated` — content changed and was rewritten (file was pristine or `--force`).
+     * - `unchanged` — already matched the current render; nothing written.
+     * - `recreated` — file was missing and was written from the render.
+     * - `conflict` — on-disk content diverged from the recorded hash; left untouched (no `--force`).
+     * - `overwritten` — diverged but rewritten because `--force` was set.
+     */
+    status: 'updated' | 'unchanged' | 'recreated' | 'conflict' | 'overwritten';
+}
+
+/**
+ * Refresh the toolkit-owned scaffold files (CI workflow, `.gitignore`) of an existing marketplace
+ * repo at `targetDir` to match the installed tooling — the upgrade path after
+ * `pnpm up @ai-plugin-marketplace/*`. Guarded by the `.aipm/scaffold.json` content-hash sidecar:
+ * user-modified files are reported as conflicts and left untouched unless `opts.force` is set.
+ * Returns one outcome per managed file; never rejects on conflict.
+ *
+ * @public
+ */
+export declare function refreshScaffold(targetDir: string, opts?: RefreshOptions): Promise<RefreshOutcome[]>;
+
+/**
+ * Scaffold a new plugin under the cwd's configured plugins root (`<cwd>/plugins/<name>` by
+ * default, or the relocated `pluginsRoot` from an `aipm.repo.ts`). The plugins directory is
+ * derived from the current working directory, matching how `aipm scaffold` is invoked from a repo
+ * root.
  *
  * @public
  */
@@ -257,7 +440,7 @@ export declare interface SupportReport {
  *
  * @public
  */
-export declare type TargetId = 'claude' | 'cursor' | 'gemini' | 'kiro' | 'vercel';
+export declare type TargetId = 'claude' | 'codex' | 'cursor' | 'gemini' | 'kiro' | 'vercel';
 
 /**
  * Validate a single plugin or every plugin under a repo root, in the order defined by §10.1.

package/dist/index.d.ts

@@ -8,8 +8,8 @@
  *
  * @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';
+export { defineConfig, defineRepoConfig, defineWorkspace } from './config.js';
+export type { AipmConfig, AipmConfigInput, AipmRepoConfig, AipmRepoConfigInput, AipmWorkspace, AipmWorkspaceInput, } from './config.js';
+export { build, validate, scaffold, init, refreshScaffold, migrate, checkSupport, addTarget, listTargets, } from './pipeline/operations.js';
+export type { TargetId, BuildOptions, BuildResult, GeneratedFile, ValidateOptions, ValidationResult, Finding, FindingCode, ScaffoldOptions, InitOptions, RefreshOptions, RefreshOutcome, MigrateOptions, MigrateResult, SupportReport, } from './pipeline/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EACV,UAAU,EACV,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,eAAe,EACf,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,cAAc,EACd,cAAc,EACd,aAAa,EACb,aAAa,GACd,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -8,6 +8,6 @@
  *
  * @packageDocumentation
  */
-export { defineConfig } from './config.js';
-export { build, validate, scaffold, init, migrate, checkSupport, addTarget, listTargets, } from './pipeline/operations.js';
+export { defineConfig, defineRepoConfig, defineWorkspace } from './config.js';
+export { build, validate, scaffold, init, refreshScaffold, migrate, checkSupport, addTarget, listTargets, } from './pipeline/operations.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/pipeline/build.d.ts

@@ -14,8 +14,10 @@
  *
  * @see docs/specs/architecture.md §5.2 (build phase), §5.4 (phase invariants), §7.2, §10.5
  */
+import type { AipmWorkspace } from '../config.js';
+import type { ConfigCache } from './load-config.js';
 import type { SentinelMode } from './sentinel.js';
-import type { BuildOptions, BuildResult, TargetId } from './types.js';
+import type { BuildOptions, BuildResult, Finding, 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
@@ -64,6 +66,161 @@ export interface DistBundle {
  * build (calls `regenerate(destDir)`) and freshness (calls `regenerate(tempDir)` then compares).
  */
 export declare function computeDistBundles(pluginDir: string, distDir: string, envelope: readonly TargetId[]): DistBundle[];
+/**
+ * One discovered plugin's contribution to registry generation. The repo-level
+ * {@link computeRegistryArtifacts} step assembles these (loading each plugin's `aipm.config.ts`
+ * for `description`/`keywords` and its envelope) so the registry generator never re-reads disk.
+ */
+export interface RegistryPluginInfo {
+    /** Plugin directory basename (the registry entry `name`). */
+    name: string;
+    /**
+     * The plugin directory relative to the repo root, `./`-prefixed and POSIX-separated (e.g.
+     * `./plugins/<name>`). This is the registry entry's `source` (string for Claude/Cursor, the
+     * `source.path` for Codex). Honors a relocated `pluginsRoot`.
+     */
+    source: string;
+    /** The plugin's declared support envelope (`config.targets`). */
+    envelope: readonly TargetId[];
+    /** Optional one-line description from `aipm.config.ts`; maps to the entry `description`/`tags` host. */
+    description?: string;
+    /** Optional keywords from `aipm.config.ts`; maps to the entry `tags` (Claude/Cursor). */
+    keywords?: readonly string[];
+}
+/**
+ * A generated marketplace registry file. Like `dist/` bundles, registries are **sentinel-less**:
+ * the host schemas are strict and there is no companion sidecar, so freshness is a whole-file
+ * regenerate-and-byte-compare against `expectedContent`. Both `runBuild` (which writes the bytes)
+ * and the freshness check (which compares disk to the bytes) derive these from one place.
+ */
+export interface RegistryArtifact {
+    /** The registry-backed target this file serves. */
+    target: TargetId;
+    /** Absolute path of the registry file (always at the repo root). */
+    absPath: string;
+    /** Exact bytes the build writes (2-space JSON + trailing newline). */
+    expectedContent: string;
+}
+/**
+ * Absolute paths of every registry the toolkit MANAGES under a repo root (one per registry-backed
+ * target), regardless of whether the current envelope produces it. Used to detect **orphaned**
+ * registries — a committed `marketplace.json` for a target no longer declared by any plugin —
+ * which `runBuild` removes and the validator flags as stale. Shared so build and validate agree
+ * on exactly which files generation owns (and never touch anything else).
+ */
+export declare function managedRegistryPaths(repoRoot: string): string[];
+/**
+ * Compute the generated marketplace registries for a repo, **without writing**. The single source
+ * of truth shared by `runBuild` (which writes `expectedContent`) and the freshness check (which
+ * compares the on-disk bytes against it).
+ *
+ * A registry file is produced for each registry-backed target (`claude` → `.claude-plugin/`,
+ * `cursor` → `.cursor-plugin/`, `codex` → `.agents/plugins/`) that appears in **at least one**
+ * plugin's envelope. Each registry lists exactly the plugins whose envelope includes that target,
+ * in the order given (callers pass plugins sorted by discovery). Registries are sentinel-less.
+ *
+ * @param repoRoot - Absolute repo root (where the registries live).
+ * @param plugins - Discovered plugins with name/source/envelope/description/keywords.
+ * @param workspace - The validated `aipm.workspace.ts` metadata.
+ */
+export declare function computeRegistryArtifacts(repoRoot: string, plugins: readonly RegistryPluginInfo[], workspace: AipmWorkspace): RegistryArtifact[];
+/**
+ * Assemble the {@link RegistryPluginInfo} for every discovered plugin under `repoRoot`, loading
+ * each plugin's `aipm.config.ts` for its envelope, description, and keywords. Shared by `runBuild`
+ * and the freshness check so both feed `computeRegistryArtifacts` identical input.
+ *
+ * @param repoRoot - Absolute repo root (the base for the `./`-prefixed `source`).
+ * @param pluginDirs - Absolute plugin directories (already discovery-sorted).
+ */
+export declare function collectRegistryPlugins(repoRoot: string, pluginDirs: readonly string[], cache?: ConfigCache): Promise<RegistryPluginInfo[]>;
+/**
+ * The hosts that have NO multi-plugin marketplace concept: each installs exactly ONE
+ * extension/power per repo, read from the **repo root**. `gemini extensions install <git>` reads a
+ * root `gemini-extension.json`; Kiro "Add from GitHub" reads a root `POWER.md`. Because the repo
+ * root has a single slot per host, at most one plugin may declare each — see the N=1 gate below.
+ */
+declare const SINGLE_ARTIFACT_HOSTS: readonly ["gemini", "kiro"];
+/** A single-artifact host (`gemini` | `kiro`). */
+type SingleArtifactHost = (typeof SINGLE_ARTIFACT_HOSTS)[number];
+/** Absolute path of the generated-root sidecar manifest under `repoRoot`. */
+export declare function rootManifestPath(repoRoot: string): string;
+/**
+ * A single repo-root file the toolkit generates for a single-artifact host. `relPath` is the path
+ * relative to the repo root (POSIX-separated, the tracked-set form); `content` is the exact bytes.
+ */
+interface RootArtifactFile {
+    /** Repo-root-relative POSIX path (e.g. `gemini-extension.json`, `commands/foo.toml`). */
+    relPath: string;
+    /** The host whose bundle produced this file. */
+    host: SingleArtifactHost;
+    /** Exact bytes to write at the repo root. */
+    content: Buffer;
+}
+/**
+ * Result of {@link computeRootArtifacts}: the repo-root files to emit (across all single-artifact
+ * hosts that passed the N=1 gate), the set of repo-root-relative paths generation owns, and any
+ * `single-artifact-host` findings for hosts that more than one plugin declared (whose root artifact
+ * is suppressed).
+ */
+export interface RootArtifacts {
+    /** Files to write at the repo root (empty if no host is emittable). */
+    files: RootArtifactFile[];
+    /** Repo-root-relative POSIX paths the toolkit generated this run (the tracked set). Sorted. */
+    trackedPaths: string[];
+    /** Hard `single-artifact-host` findings — one per host declared by more than one plugin. */
+    findings: Finding[];
+}
+/**
+ * Compute the repo-root native artifacts for the single-artifact hosts (`gemini`, `kiro`),
+ * **without writing**. The single source of truth shared by `runBuild` (which writes the files,
+ * applies the collision guard, and orphan-removes) and the freshness check (which compares disk to
+ * these bytes). Bundling happens into a throwaway temp dir — the repo root is never passed to a
+ * bundler, so the bundlers' `rmSync(destDir)` can never touch repo-root state.
+ *
+ * **N=1 gate (`single-artifact-host`).** For each host, count the plugins whose envelope declares
+ * it. Exactly one declarer → emit that plugin's bundled files at the repo root. More than one →
+ * emit a hard `single-artifact-host` finding and emit NOTHING for that host (the toolkit can't pick
+ * which plugin owns the single root slot). Zero → nothing to emit (and no finding). The two hosts
+ * are independent: a repo where plugin A declares `gemini` and plugin B declares `kiro` emits both
+ * (a root `gemini-extension.json` and a root `POWER.md` — distinct files).
+ *
+ * @param repoRoot - Absolute repo root (where the artifacts live). Accepted for signature
+ *   parallelism with {@link computeRegistryArtifacts}; the bundlers read only the plugin dir.
+ * @param plugins - Discovered plugins with name/source/envelope (the registry plugin infos already
+ *   collected for {@link computeRegistryArtifacts}). Each `source` resolves the plugin dir.
+ * @param _workspace - The validated workspace metadata. Unused by the bundlers today; accepted for
+ *   parallelism with the registry compute signature and to future-proof host metadata injection.
+ */
+export declare function computeRootArtifacts(repoRoot: string, plugins: readonly RegistryPluginInfo[], _workspace: AipmWorkspace): RootArtifacts;
+/**
+ * Detect repo-root collisions for the freshly computed {@link RootArtifacts}, given the PRIOR
+ * tracked set. A file collides when it exists on disk AND its repo-root-relative path is NOT in the
+ * prior tracked set — i.e. it is not something the toolkit previously created, so it belongs to the
+ * host/author and must not be clobbered (safety guard 3). A clean repo (no pre-existing root files)
+ * never collides. Collision is evaluated PER HOST: if any of a host's files collide, that host is
+ * suppressed entirely (no partial writes) and a single finding names the first offending path.
+ *
+ * Returns the collision findings plus the set of hosts that collided (so the caller can skip
+ * writing/tracking their files). Pure — no I/O beyond `existsSync`.
+ */
+export declare function detectRootCollisions(repoRoot: string, artifacts: RootArtifacts, priorTracked: readonly string[]): {
+    findings: Finding[];
+    collidedHosts: Set<SingleArtifactHost>;
+};
+/**
+ * Serialize the generated-root sidecar manifest. Shape: `{ version: 1, paths: string[] }` where
+ * `paths` is the sorted set of repo-root-relative POSIX paths the toolkit generated (the sidecar
+ * itself is NOT listed — it is tracked separately and always lives at {@link rootManifestPath}).
+ * 2-space JSON + trailing newline, byte-stable so the freshness compare is exact.
+ */
+export declare function serializeRootManifest(trackedPaths: readonly string[]): string;
+/**
+ * Read the prior generated-root sidecar manifest, returning the tracked-path set it recorded.
+ * Returns an empty array when the sidecar is absent or unparseable — a missing/corrupt sidecar is
+ * treated as "nothing tracked yet" (a clean first build), and the collision guard then protects any
+ * pre-existing root files. POSIX-separated paths are returned as-is.
+ */
+export declare function readRootManifestPaths(repoRoot: string): string[];
 /** Collect every file path under `dir`, relative to `dir`. Returns `[]` if `dir` is absent. */
 export declare function collectFilesRelative(dir: string): string[];
 /**
@@ -87,4 +244,5 @@ export declare function runBuild(targetPath: string, opts?: BuildOptions): Promi
  * on-disk bundle without disturbing it.
  */
 export declare function regenerateBundleToTemp(bundle: DistBundle): string;
+export {};
 //# sourceMappingURL=build.d.ts.map