@shrkcrft/presets 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+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,15 @@
+# @shrkcrft/presets
+
+SharkCraft presets: reusable project setups (knowledge/rules/paths/templates/pipelines/docs) that can be applied to a target repo through the CLI.
+
+Part of [SharkCraft](https://github.com/sharkcraft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/presets
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/apply/preview-apply.d.ts

@@ -0,0 +1,52 @@
+import type { IPreset } from '../model/preset.js';
+import { type ISynthesizedFile } from '../emit/synthesize-files.js';
+import type { IResolvedPreset } from '../registry/resolve-preset.js';
+export interface IPresetApplyPlanEntry {
+    /** Absolute target path inside the project. */
+    targetPath: string;
+    /** Path relative to project root. */
+    relPath: string;
+    status: 'create' | 'skip-existing' | 'overwrite-with-force' | 'merge-additive';
+    content: string;
+    kind: ISynthesizedFile['kind'];
+}
+export interface IPresetApplyPlan {
+    presetId: string;
+    sharkcraftDir: string;
+    entries: IPresetApplyPlanEntry[];
+    warnings: string[];
+}
+export interface IPreviewOptions {
+    /** Absolute project root. */
+    projectRoot: string;
+    /** Force overwriting existing files. */
+    force?: boolean;
+    /** Append to existing files where possible (knowledge/rules/paths/templates/pipelines). */
+    merge?: boolean;
+    /** Override the sharkcraft directory name (default: "sharkcraft"). */
+    sharkcraftDirName?: string;
+}
+/**
+ * Compute the plan for applying a preset against `projectRoot`. Pure I/O on
+ * read; never writes. Caller is responsible for executing the plan via
+ * {@link applyPlan} (or just printing it).
+ */
+export declare function previewPresetApplication(preset: IPreset, options: IPreviewOptions): IPresetApplyPlan;
+/**
+ * Same as {@link previewPresetApplication} but operating on a flattened
+ * (composition-resolved) preset. Use this whenever composition matters —
+ * which is the common case once `composes: [...]` is in play.
+ */
+export declare function previewResolvedPresetApplication(resolved: IResolvedPreset, options: IPreviewOptions): IPresetApplyPlan;
+/**
+ * Execute a plan. Writes files according to each entry's status. Returns the
+ * list of relPaths actually written.
+ *
+ * For `merge-additive`, we append the new content under a generated banner.
+ * No semantic re-parsing is performed — review the result.
+ */
+export declare function applyPresetPlan(plan: IPresetApplyPlan): {
+    written: string[];
+    skipped: string[];
+};
+//# sourceMappingURL=preview-apply.d.ts.map

package/dist/apply/preview-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-apply.d.ts","sourceRoot":"","sources":["../../src/apply/preview-apply.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,sBAAsB,GAAG,gBAAgB,CAAC;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2FAA2F;IAC3F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAUD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,eAAe,GACvB,gBAAgB,CAElB;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,eAAe,GACvB,gBAAgB,CAMlB;AAwCD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAoBA"}

package/dist/apply/preview-apply.js

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { synthesizePresetFiles, synthesizeResolvedPresetFiles, } from "../emit/synthesize-files.js";
+const MERGABLE_KINDS = new Set([
+    'knowledge',
+    'rules',
+    'paths',
+    'templates',
+    'pipelines',
+]);
+/**
+ * Compute the plan for applying a preset against `projectRoot`. Pure I/O on
+ * read; never writes. Caller is responsible for executing the plan via
+ * {@link applyPlan} (or just printing it).
+ */
+export function previewPresetApplication(preset, options) {
+    return previewFromSynthesized(preset.id, synthesizePresetFiles(preset), options);
+}
+/**
+ * Same as {@link previewPresetApplication} but operating on a flattened
+ * (composition-resolved) preset. Use this whenever composition matters —
+ * which is the common case once `composes: [...]` is in play.
+ */
+export function previewResolvedPresetApplication(resolved, options) {
+    return previewFromSynthesized(resolved.rootId, synthesizeResolvedPresetFiles(resolved), options);
+}
+function previewFromSynthesized(presetId, synthesized, options) {
+    const sharkcraftDir = nodePath.join(options.projectRoot, options.sharkcraftDirName ?? 'sharkcraft');
+    const entries = [];
+    const warnings = [];
+    for (const file of synthesized) {
+        const targetPath = nodePath.join(sharkcraftDir, file.path);
+        const relPath = nodePath.relative(options.projectRoot, targetPath);
+        let status = 'create';
+        if (existsSync(targetPath)) {
+            if (options.force) {
+                status = 'overwrite-with-force';
+            }
+            else if (options.merge && MERGABLE_KINDS.has(file.kind)) {
+                status = 'merge-additive';
+            }
+            else {
+                status = 'skip-existing';
+                warnings.push(`exists, skipping: ${relPath} (use --force or --merge)`);
+            }
+        }
+        entries.push({
+            targetPath,
+            relPath,
+            status,
+            content: file.content,
+            kind: file.kind,
+        });
+    }
+    return { presetId, sharkcraftDir, entries, warnings };
+}
+/**
+ * Execute a plan. Writes files according to each entry's status. Returns the
+ * list of relPaths actually written.
+ *
+ * For `merge-additive`, we append the new content under a generated banner.
+ * No semantic re-parsing is performed — review the result.
+ */
+export function applyPresetPlan(plan) {
+    const written = [];
+    const skipped = [];
+    for (const entry of plan.entries) {
+        if (entry.status === 'skip-existing') {
+            skipped.push(entry.relPath);
+            continue;
+        }
+        const dir = nodePath.dirname(entry.targetPath);
+        mkdirSync(dir, { recursive: true });
+        if (entry.status === 'merge-additive' && existsSync(entry.targetPath)) {
+            const previous = readFileSync(entry.targetPath, 'utf8');
+            const banner = `\n\n// --- merged from preset ${plan.presetId} ---\n`;
+            writeFileSync(entry.targetPath, previous + banner + entry.content, 'utf8');
+        }
+        else {
+            writeFileSync(entry.targetPath, entry.content, 'utf8');
+        }
+        written.push(entry.relPath);
+    }
+    return { written, skipped };
+}

package/dist/builtin/builtin-presets.d.ts

@@ -0,0 +1,3 @@
+import type { IPreset } from '../model/preset.js';
+export declare const BUILTIN_PRESETS: readonly IPreset[];
+//# sourceMappingURL=builtin-presets.d.ts.map

package/dist/builtin/builtin-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-presets.d.ts","sourceRoot":"","sources":["../../src/builtin/builtin-presets.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AA6iBlD,eAAO,MAAM,eAAe,EAAE,SAAS,OAAO,EA0B5C,CAAC"}