@ai-plugin-marketplace/core 0.1.0

package/dist/pipeline/scaffold.js

@@ -0,0 +1,422 @@
+/**
+ * Pipeline orchestration for scaffolding and compatibility-assist (§6.4).
+ *
+ * Three orchestrators perform filesystem I/O around the per-target *pure* scaffold functions:
+ *
+ *   - `runScaffold`     — create a brand-new plugin (the `aipm scaffold` surface).
+ *   - `runAddTarget`    — add one target's skeleton to an existing plugin (`aipm add-target`).
+ *   - `runCheckSupport` — report declared-but-incomplete and plausibly-addable targets
+ *                          (`aipm check-support`).
+ *
+ * Per §3.4/§12.4 the pipeline layer is the orchestration boundary and MAY import each target's
+ * `scaffold.ts`; the per-target scaffold modules themselves never import one another.
+ *
+ * Envelope reading (§6.1): loading and executing a TypeScript `aipm.config.ts` from disk is the
+ * build orchestrator's job and is not yet built. `runCheckSupport`/`runAddTarget` therefore read
+ * the declared targets *pragmatically* — by extracting the `targets: [...]` array literal out of
+ * the config source text (see `parseDeclaredTargets`). This tolerates the canonical
+ * `defineConfig({ ... })` form this module emits and common hand-authored variants, but it is a
+ * lexical heuristic, not a TS evaluation. Documented limitation: a config that computes `targets`
+ * dynamically (spread, variable reference, conditional) is not understood and yields an error.
+ *
+ * @see docs/specs/architecture.md §6 (support envelope)
+ * @see docs/specs/architecture.md §6.4 (compatibility-assist tooling)
+ * @see docs/specs/architecture.md §10.1 (validation contract — artifact tables reused here)
+ * @see docs/specs/architecture.md §12.5 (per-target scaffold.ts)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { scaffoldClaudeFiles } from '../targets/claude/scaffold.js';
+import { scaffoldCursorFiles } from '../targets/cursor/scaffold.js';
+import { scaffoldGeminiFiles } from '../targets/gemini/scaffold.js';
+import { scaffoldKiroFiles } from '../targets/kiro/scaffold.js';
+import { scaffoldVercelFiles } from '../targets/vercel/scaffold.js';
+import { SCHEMA_VERSION } from '../targets/scaffold-kit.js';
+import { TARGET_IDS } from './types.js';
+import { TARGET_MIN_REQUIRED } from './validate.js';
+// ---------------------------------------------------------------------------
+// Per-target scaffold dispatch
+// ---------------------------------------------------------------------------
+/** Map a target ID to its pure scaffold function. */
+const TARGET_SCAFFOLDERS = {
+    claude: scaffoldClaudeFiles,
+    cursor: scaffoldCursorFiles,
+    gemini: scaffoldGeminiFiles,
+    kiro: scaffoldKiroFiles,
+    vercel: scaffoldVercelFiles,
+};
+const md = String.raw;
+const ts = String.raw;
+// ---------------------------------------------------------------------------
+// Name validation (mirrors the slug rules enforced by the manifest schemas)
+// ---------------------------------------------------------------------------
+/**
+ * Validate a plugin name against the canonical slug rules shared by every manifest schema:
+ * lowercase, starts with a letter, `[a-z0-9-]` only, no consecutive hyphens, no trailing hyphen.
+ *
+ * @throws Error with a clear message when the name is invalid.
+ */
+export function validatePluginName(name) {
+    if (name === '') {
+        throw new Error('Plugin name is required.');
+    }
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+        throw new Error(`Invalid plugin name: "${name}". Names must be lowercase, start with a letter, and contain only letters, digits, and hyphens.`);
+    }
+    if (name.includes('--')) {
+        throw new Error(`Invalid plugin name: "${name}". Names must not contain consecutive hyphens.`);
+    }
+    if (name.endsWith('-')) {
+        throw new Error(`Invalid plugin name: "${name}". Names must not end with a hyphen.`);
+    }
+}
+// ---------------------------------------------------------------------------
+// aipm.config.ts generation + parsing
+// ---------------------------------------------------------------------------
+/**
+ * Render the canonical `aipm.config.ts` source for a plugin with the given targets.
+ *
+ * Emits a `defineConfig({ version, targets })` literal importing from the public package root
+ * (§8.1 — the only public subpath). Deterministic: stable target ordering, no timestamps.
+ */
+export function renderAipmConfig(targets) {
+    const ordered = orderTargets(targets);
+    const targetList = ordered.map((t) => `'${t}'`).join(', ');
+    return ts `import { defineConfig } from '@ai-plugin-marketplace/core';
+
+export default defineConfig({
+  version: '${SCHEMA_VERSION}',
+  targets: [${targetList}],
+});
+`;
+}
+/**
+ * Extract the declared targets from `aipm.config.ts` source text.
+ *
+ * Lexical heuristic (see module doc): finds the first `targets:` key and parses the immediately
+ * following `[...]` array of single/double-quoted string literals. Only IDs in `TARGET_IDS` are
+ * returned; unknown IDs are ignored (the shape validator surfaces those separately).
+ *
+ * @returns Declared target IDs in canonical order, deduplicated.
+ * @throws Error when no `targets: [...]` array literal can be located.
+ */
+export function parseDeclaredTargets(configSource) {
+    // Match `targets` followed by optional whitespace, a colon, then a bracketed list.
+    const match = /targets\s*:\s*\[([^\]]*)\]/.exec(configSource);
+    if (!match) {
+        throw new Error('Could not locate a `targets: [...]` array literal in aipm.config.ts. ' +
+            'Dynamically-computed targets are not supported by the lexical envelope reader.');
+    }
+    const inner = match[1] ?? '';
+    const ids = [...inner.matchAll(/['"]([^'"]+)['"]/g)].map((m) => m[1] ?? '');
+    const known = new Set(TARGET_IDS);
+    const declared = ids.filter((id) => known.has(id));
+    return orderTargets([...new Set(declared)]);
+}
+/** Order a target set by the canonical `TARGET_IDS` ordering. Deterministic output. */
+function orderTargets(targets) {
+    const present = new Set(targets);
+    return TARGET_IDS.filter((t) => present.has(t));
+}
+// ---------------------------------------------------------------------------
+// Marketplace registration (§4.4, §10.1.4)
+// ---------------------------------------------------------------------------
+/**
+ * The template-level marketplace registries that a plugin must be registered in, keyed by the
+ * target whose presence in the envelope requires registration (§4.4). Both registries live at the
+ * **repo root**, not inside any plugin: `<repoRoot>/.claude-plugin/marketplace.json` (Claude) and
+ * `<repoRoot>/.cursor-plugin/marketplace.json` (Cursor).
+ *
+ * Mirrors `validateMarketplaceRegistration` in `validate.ts`: those two targets, those two paths.
+ */
+const MARKETPLACE_REGISTRIES = [
+    { target: 'claude', dir: '.claude-plugin' },
+    { target: 'cursor', dir: '.cursor-plugin' },
+];
+/** The canonical `source` value for a plugin's registry entry (§4.4 — `./plugins/<name>`). */
+function expectedSource(pluginName) {
+    return `./plugins/${pluginName}`;
+}
+/**
+ * Register `pluginName` in the registry file at `registryPath`, creating it if absent.
+ *
+ * Idempotent: if an entry whose `name` already matches `pluginName` exists, the file is left
+ * untouched (no duplicate, no source rewrite — repairing a wrong source is the validator's job to
+ * report, not the scaffolder's to silently mutate). Output is 2-space JSON with a trailing newline.
+ *
+ * Existing entries and any extra top-level keys are preserved.
+ */
+function registerInMarketplace(registryPath, pluginName) {
+    const entry = { name: pluginName, source: expectedSource(pluginName) };
+    let registry;
+    if (fs.existsSync(registryPath)) {
+        const raw = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+        // Tolerate a missing/!object/!plugins file by normalizing to a registry with a plugins array.
+        registry =
+            typeof raw === 'object' && raw !== null ? raw : { plugins: [] };
+    }
+    else {
+        registry = { plugins: [] };
+    }
+    const plugins = Array.isArray(registry.plugins) ? registry.plugins : [];
+    if (plugins.some((p) => p.name === pluginName)) {
+        return; // already registered — idempotent no-op
+    }
+    registry.plugins = [...plugins, entry];
+    writeFileEnsuringDir(registryPath, `${JSON.stringify(registry, null, 2)}\n`);
+}
+/**
+ * Register a plugin in every marketplace registry implied by its envelope (§4.4).
+ *
+ * For each of Claude/Cursor present in `targets`, create-or-append the plugin's entry in the
+ * corresponding `<repoRoot>/<dir>/marketplace.json`. Targets not in the envelope get no entry, so
+ * the scaffold→validate happy path stays clean (the validator forbids registration for
+ * undeclared targets).
+ */
+function registerPluginInMarketplaces(repoRoot, pluginName, targets) {
+    const envelope = new Set(targets);
+    for (const { target, dir } of MARKETPLACE_REGISTRIES) {
+        if (!envelope.has(target))
+            continue;
+        registerInMarketplace(path.join(repoRoot, dir, 'marketplace.json'), pluginName);
+    }
+}
+// ---------------------------------------------------------------------------
+// Filesystem helpers
+// ---------------------------------------------------------------------------
+/** Write `content` to `filePath`, creating parent directories. Does not check for existence. */
+function writeFileEnsuringDir(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf-8');
+}
+/**
+ * Canonical top-level files every scaffolded plugin gets, independent of targets (§4 layout).
+ * Deterministic: no clock/env reads — the LICENSE year is intentionally omitted.
+ */
+function canonicalRootFiles(pluginName, description) {
+    const readme = md `# ${pluginName}
+
+${description}
+
+## Installation
+
+Install this plugin by copying it into your AI assistant's plugin directory.
+
+## License
+
+ISC
+`;
+    const license = `ISC License
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+`;
+    return [
+        { path: 'README.md', content: readme },
+        { path: 'LICENSE', content: license },
+    ];
+}
+// ---------------------------------------------------------------------------
+// runScaffold
+// ---------------------------------------------------------------------------
+/**
+ * Create a brand-new plugin under `pluginsDir/<name>/`.
+ *
+ * Writes `aipm.config.ts` (via the `defineConfig` literal), each declared target's skeleton
+ * files, and the canonical `README.md` / `LICENSE`. Default targets are all known IDs when
+ * `opts.targets` is absent.
+ *
+ * Also registers the plugin in the template-level marketplace registries (§4.4) for each of
+ * Claude/Cursor in the envelope (`repoRoot = dirname(pluginsDir)`), so the scaffolded plugin
+ * passes `validate`'s `marketplace-registration` check (§10.1.4) out of the box.
+ *
+ * @throws Error when `name` is invalid or the plugin directory already exists.
+ */
+export async function runScaffold(name, pluginsDir, opts = {}) {
+    validatePluginName(name);
+    const pluginDir = path.join(pluginsDir, name);
+    if (fs.existsSync(pluginDir)) {
+        throw new Error(`Plugin directory already exists: ${pluginDir}`);
+    }
+    const targets = orderTargets(opts.targets ?? TARGET_IDS);
+    const description = opts.description ?? `A plugin for ${name}`;
+    const targetOpts = { description };
+    const files = [
+        { path: 'aipm.config.ts', content: renderAipmConfig(targets) },
+        ...canonicalRootFiles(name, description),
+    ];
+    for (const target of targets) {
+        files.push(...TARGET_SCAFFOLDERS[target](name, targetOpts));
+    }
+    fs.mkdirSync(pluginDir, { recursive: true });
+    for (const file of files) {
+        writeFileEnsuringDir(path.join(pluginDir, file.path), file.content);
+    }
+    // Register in the repo-root marketplace registries (§4.4). repoRoot is the parent of pluginsDir.
+    registerPluginInMarketplaces(path.dirname(pluginsDir), name, targets);
+    return Promise.resolve();
+}
+// ---------------------------------------------------------------------------
+// runAddTarget
+// ---------------------------------------------------------------------------
+/**
+ * Scaffold one target's skeleton files into an existing plugin (§6.4 `aipm add-target`).
+ *
+ * Manifest fields are emitted as placeholders for the author to complete. Existing files are
+ * NEVER clobbered: if any file this target would write already exists, the function refuses and
+ * throws — the author resolves the conflict deliberately.
+ *
+ * The plugin's `aipm.config.ts` is updated to include `target` in its `targets` array when the
+ * lexical reader can locate the array (see module doc). Limitation: if the array cannot be parsed
+ * (dynamic/computed targets), the config is left untouched and the error message instructs the
+ * author to add the target manually — the function never leaves the envelope silently
+ * inconsistent.
+ *
+ * When `target` is Claude or Cursor, the plugin is also registered in the corresponding
+ * repo-root marketplace registry (§4.4) so adding the target keeps `validate` green. repoRoot is
+ * the plugin's grandparent (`<repoRoot>/plugins/<name>`), matching `discoverPlugins`.
+ *
+ * @throws Error when `pluginDir` does not exist, a target file already exists, or the config's
+ * targets array cannot be located for the update.
+ */
+export async function runAddTarget(pluginDir, target) {
+    if (!fs.existsSync(pluginDir)) {
+        throw new Error(`Plugin directory does not exist: ${pluginDir}`);
+    }
+    const pluginName = path.basename(pluginDir);
+    const files = TARGET_SCAFFOLDERS[target](pluginName, { placeholder: true });
+    // Refuse to overwrite: collect conflicts before writing anything.
+    const conflicts = files
+        .map((f) => f.path)
+        .filter((rel) => fs.existsSync(path.join(pluginDir, rel)));
+    if (conflicts.length > 0) {
+        throw new Error(`Refusing to overwrite existing files while adding target '${target}': ${conflicts.join(', ')}. ` +
+            'Remove or move them first, then re-run.');
+    }
+    // Update the envelope BEFORE writing skeleton files, so a config we cannot parse aborts the
+    // whole operation rather than leaving orphan files with an unchanged envelope.
+    updateConfigTargets(pluginDir, target);
+    for (const file of files) {
+        writeFileEnsuringDir(path.join(pluginDir, file.path), file.content);
+    }
+    // Register in the repo-root marketplace registry when adding a registry-backed target (§4.4).
+    // repoRoot = dirname(dirname(pluginDir)) — the `<repoRoot>/plugins/<name>` grandparent.
+    registerPluginInMarketplaces(path.dirname(path.dirname(pluginDir)), pluginName, [target]);
+    return Promise.resolve();
+}
+/**
+ * Add `target` to the `targets` array in `pluginDir/aipm.config.ts`, rewriting the file.
+ *
+ * Idempotent: if `target` is already declared, the file is left byte-for-byte unchanged.
+ * Always re-renders the array in canonical order. Throws (rather than silently skipping) when the
+ * config is missing or the array cannot be located, so the caller never proceeds with an
+ * inconsistent envelope.
+ */
+function updateConfigTargets(pluginDir, target) {
+    const configPath = path.join(pluginDir, 'aipm.config.ts');
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`Cannot add target '${target}': no aipm.config.ts found at ${configPath}. ` +
+            'Create one declaring the support envelope first.');
+    }
+    const source = fs.readFileSync(configPath, 'utf-8');
+    const declared = parseDeclaredTargets(source); // throws if no array literal located
+    if (declared.includes(target)) {
+        return; // already declared — nothing to do
+    }
+    const next = orderTargets([...declared, target]);
+    const targetList = next.map((t) => `'${t}'`).join(', ');
+    const rewritten = source.replace(/targets\s*:\s*\[[^\]]*\]/, `targets: [${targetList}]`);
+    fs.writeFileSync(configPath, rewritten, 'utf-8');
+}
+// ---------------------------------------------------------------------------
+// runCheckSupport
+// ---------------------------------------------------------------------------
+/**
+ * Report a plugin's support posture (§6.4 `aipm check-support`).
+ *
+ * Reads the declared envelope from `aipm.config.ts` (lexically — see module doc), then:
+ *   - `missingArtifacts`: for each declared target, the `TARGET_MIN_REQUIRED` files absent on disk
+ *     (Vercel's "at least one SKILL.md under a skills subdirectory" rule is applied specially,
+ *     mirroring the
+ *     validator). Only targets with at least one missing artifact appear.
+ *   - `suggestions`: each undeclared known target, with `wouldNeed` = that target's min-required
+ *     files (the concrete list of files the author would write to add it).
+ *
+ * Reuses the validator's `TARGET_MIN_REQUIRED` table so "missing" stays consistent with
+ * `aipm validate`.
+ *
+ * @throws Error when `pluginDir` or its `aipm.config.ts` is missing, or the envelope is unreadable.
+ */
+export async function runCheckSupport(pluginDir) {
+    if (!fs.existsSync(pluginDir)) {
+        throw new Error(`Plugin directory does not exist: ${pluginDir}`);
+    }
+    const configPath = path.join(pluginDir, 'aipm.config.ts');
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`No aipm.config.ts found at ${configPath}.`);
+    }
+    const source = fs.readFileSync(configPath, 'utf-8');
+    const declared = parseDeclaredTargets(source);
+    const declaredSet = new Set(declared);
+    const missingArtifacts = [];
+    for (const target of declared) {
+        const missing = missingMinRequired(pluginDir, target);
+        if (missing.length > 0) {
+            missingArtifacts.push({ target, missing });
+        }
+    }
+    const suggestions = TARGET_IDS.filter((t) => !declaredSet.has(t)).map((target) => ({ target, wouldNeed: wouldNeedArtifacts(target) }));
+    return Promise.resolve({
+        plugin: path.basename(pluginDir),
+        declared,
+        missingArtifacts,
+        suggestions,
+    });
+}
+/**
+ * The min-required artifacts for `target` that are absent under `pluginDir`.
+ *
+ * Vercel has no entry in `TARGET_MIN_REQUIRED` (its requirement is "at least one
+ * a SKILL.md under a skills subdirectory", a directory-scan rule), so it is handled specially to
+ * match the validator.
+ */
+function missingMinRequired(pluginDir, target) {
+    if (target === 'vercel') {
+        return hasAnyVercelSkill(pluginDir) ? [] : ['skills/<skill-name>/SKILL.md'];
+    }
+    return TARGET_MIN_REQUIRED[target].filter((rel) => !fs.existsSync(path.join(pluginDir, rel)));
+}
+/** The concrete files an author would write to add `target` (mirrors `missingMinRequired`). */
+function wouldNeedArtifacts(target) {
+    if (target === 'vercel') {
+        return ['skills/<skill-name>/SKILL.md'];
+    }
+    return [...TARGET_MIN_REQUIRED[target]];
+}
+/** True iff at least one `skills/<dir>/SKILL.md` exists one level under `pluginDir/skills`. */
+function hasAnyVercelSkill(pluginDir) {
+    const skillsDir = path.join(pluginDir, 'skills');
+    if (!fs.existsSync(skillsDir))
+        return false;
+    try {
+        for (const dirent of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+            if (dirent.isDirectory() && fs.existsSync(path.join(skillsDir, dirent.name, 'SKILL.md'))) {
+                return true;
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/pipeline/scaffold.js.map

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

package/dist/pipeline/sentinel.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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)
+ */
+import type { ClaudeHooksFile } from '../targets/claude/schemas.js';
+/**
+ * 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 declare const GENERATOR_ID = "@ai-plugin-marketplace/cli";
+/**
+ * Which sentinel carrier a given generated file uses. Selected by the build step per the
+ * artifact's format and host tolerance (§4.3):
+ * - `'inline'` — plain-text outputs (comment block prepended).
+ * - `'json-field'` — JSON outputs that tolerate an extra top-level `_generated` key.
+ * - `'sidecar'` — strict-schema JSON whose host rejects unknown fields; sentinel lives in
+ *   a companion `<artifact>.generated` file and the artifact itself is left untouched.
+ */
+export type SentinelMode = 'inline' | 'json-field' | 'sidecar';
+/**
+ * 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 declare function applyInlineSentinel(content: string, source: string): string;
+/**
+ * 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 declare function sidecarContent(source: string): string;
+/**
+ * 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 declare function sidecarPath(artifactPath: string): string;
+/**
+ * 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 declare function applyJsonSentinel(obj: unknown, source: string): string;
+/**
+ * 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 declare function applyJsonSentinelToHooks(data: ClaudeHooksFile, source: string): string;
+/**
+ * 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 declare function hasSentinel(content: string, mode: SentinelMode): boolean;
+/**
+ * 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 declare function readSentinelSource(content: string, mode: SentinelMode): string | undefined;
+/**
+ * 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 declare function stripSentinel(content: string, mode: SentinelMode): string;
+//# sourceMappingURL=sentinel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../../src/pipeline/sentinel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,YAAY,+BAA+B,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAqC/D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3E;AASD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAExD;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAmBtE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtF;AAmDD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAExE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAQ1F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAWzE"}