@shrkcrft/generator 0.1.0-alpha.2

package/dist/plan-signing.d.ts

@@ -0,0 +1,37 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { ISavedPlan } from './saved-plan.js';
+/** Env var that supplies the HMAC secret. */
+export declare const PLAN_SECRET_ENV = "SHARKCRAFT_PLAN_SECRET";
+export declare const SIGNATURE_ALGO = "sha256";
+export interface IPlanSignature {
+    /** Algorithm marker. */
+    algo: typeof SIGNATURE_ALGO;
+    /** Hex-encoded HMAC. */
+    hmac: string;
+    /** ISO timestamp of when the plan was signed. */
+    signedAt: string;
+}
+/**
+ * Stable JSON encoding for a saved plan, excluding any existing signature.
+ * Keys are sorted recursively. Used as the input to the HMAC.
+ */
+export declare function canonicalizePlan(plan: ISavedPlan): string;
+export interface SignPlanOptions {
+    /** Explicit secret. If omitted, falls back to SHARKCRAFT_PLAN_SECRET env. */
+    secret?: string;
+}
+export declare function signPlan(plan: ISavedPlan, options?: SignPlanOptions): Result<ISavedPlan, AppError>;
+export interface VerifyPlanOptions {
+    secret?: string;
+}
+export type VerifyResult = {
+    ok: true;
+    status: 'verified';
+} | {
+    ok: false;
+    status: 'missing-signature' | 'missing-secret' | 'invalid-signature';
+    message: string;
+};
+/** Pure verification: returns a discriminated status union. */
+export declare function verifyPlan(plan: ISavedPlan, options?: VerifyPlanOptions): VerifyResult;
+//# sourceMappingURL=plan-signing.d.ts.map

package/dist/plan-signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-signing.d.ts","sourceRoot":"","sources":["../src/plan-signing.ts"],"names":[],"mappings":"AACA,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,6CAA6C;AAC7C,eAAO,MAAM,eAAe,2BAA2B,CAAC;AACxD,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC,MAAM,WAAW,cAAc;IAC7B,wBAAwB;IACxB,IAAI,EAAE,OAAO,cAAc,CAAC;IAC5B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAIzD;AAwBD,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAiB9B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzG,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,iBAAsB,GAAG,YAAY,CA4B1F"}

package/dist/plan-signing.js

@@ -0,0 +1,82 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+/** Env var that supplies the HMAC secret. */
+export const PLAN_SECRET_ENV = 'SHARKCRAFT_PLAN_SECRET';
+export const SIGNATURE_ALGO = 'sha256';
+/**
+ * Stable JSON encoding for a saved plan, excluding any existing signature.
+ * Keys are sorted recursively. Used as the input to the HMAC.
+ */
+export function canonicalizePlan(plan) {
+    const clone = { ...plan };
+    delete clone.signature;
+    return canonicalJson(clone);
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => canonicalJson(v)).join(',') + ']';
+    }
+    const keys = Object.keys(value).sort();
+    const parts = [];
+    for (const k of keys) {
+        const v = value[k];
+        if (v === undefined)
+            continue;
+        parts.push(JSON.stringify(k) + ':' + canonicalJson(v));
+    }
+    return '{' + parts.join(',') + '}';
+}
+function readSecret(envSecret) {
+    if (envSecret !== undefined && envSecret.length > 0)
+        return envSecret;
+    const fromEnv = process.env[PLAN_SECRET_ENV];
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    return null;
+}
+export function signPlan(plan, options = {}) {
+    const secret = readSecret(options.secret);
+    if (!secret) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Cannot sign plan: no secret. Set ${PLAN_SECRET_ENV} or pass --secret.`));
+    }
+    const canon = canonicalizePlan(plan);
+    const hmac = createHmac(SIGNATURE_ALGO, secret).update(canon).digest('hex');
+    const signed = {
+        ...plan,
+        signature: { algo: SIGNATURE_ALGO, hmac, signedAt: new Date().toISOString() },
+    };
+    return ok(signed);
+}
+/** Pure verification: returns a discriminated status union. */
+export function verifyPlan(plan, options = {}) {
+    if (!plan.signature) {
+        return { ok: false, status: 'missing-signature', message: 'Plan has no signature.' };
+    }
+    const secret = readSecret(options.secret);
+    if (!secret) {
+        return {
+            ok: false,
+            status: 'missing-secret',
+            message: `Cannot verify plan: no secret. Set ${PLAN_SECRET_ENV} or pass --secret.`,
+        };
+    }
+    const canon = canonicalizePlan(plan);
+    const expected = createHmac(SIGNATURE_ALGO, secret).update(canon).digest();
+    let given;
+    try {
+        given = Buffer.from(plan.signature.hmac, 'hex');
+    }
+    catch {
+        return { ok: false, status: 'invalid-signature', message: 'Signature is not valid hex.' };
+    }
+    if (given.length !== expected.length) {
+        return { ok: false, status: 'invalid-signature', message: 'Signature length mismatch.' };
+    }
+    const equal = timingSafeEqual(given, expected);
+    if (!equal) {
+        return { ok: false, status: 'invalid-signature', message: 'Signature does not match.' };
+    }
+    return { ok: true, status: 'verified' };
+}

package/dist/planned-change.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Planned change model — v2.
+ *
+ * v1 templates emit CREATE-only entries via `files() → ITemplateFile[]`. The
+ * v2 model lets templates declare explicit UPDATE-style operations (append,
+ * insert-after, insert-before, replace, export) alongside CREATE entries.
+ *
+ * Each operation:
+ *   - is declared by the template as a small structured intent;
+ *   - is evaluated at plan time against the live file system;
+ *   - resolves to a concrete `IFileChange` with precomputed final contents,
+ *     a kind ("append" / "insert-after" / ... / "skip" / "conflict"),
+ *     and a reason that explains what the engine decided.
+ *
+ * Hard rules preserved by this module:
+ *   - No arbitrary code execution. Operations are data, not closures.
+ *   - No hidden post-apply hooks. Every byte written ends up in `contents` and
+ *     is shown in dry-run / plan review.
+ *   - Same write path as v1: `generator-engine.generate()` writes the
+ *     precomputed `contents`. Apply does not re-interpret the operation.
+ *   - MCP stays read-only — this module is pure logic.
+ */
+import { FileChangeType, type IFileChange } from './file-change.js';
+export type PlannedOperationKind = 'create' | 'append' | 'insert-after' | 'insert-before' | 'replace' | 'export' | 'ensure-import' | 'insert-enum-entry' | 'insert-object-entry' | 'insert-before-closing-brace' | 'insert-between-anchors';
+interface ICreateOperation {
+    kind: 'create';
+    content: string;
+    description?: string;
+}
+interface IAppendOperation {
+    kind: 'append';
+    /**
+     * The snippet to append at the end of the file. The engine adds a single
+     * `\n` separator between the existing trailing content and the snippet if
+     * the existing file does not already end with a newline.
+     */
+    snippet: string;
+    /**
+     * Optional idempotency marker. If the existing file already contains this
+     * string anywhere, the operation is skipped (already applied).
+     */
+    ifMissing?: string;
+    description?: string;
+}
+interface IInsertAfterOperation {
+    kind: 'insert-after';
+    /** Literal substring that must appear exactly once in the file. */
+    anchor: string;
+    /** The snippet to insert immediately after `anchor`. */
+    snippet: string;
+    /** Idempotency check; default = `snippet`. */
+    ifMissing?: string;
+    description?: string;
+}
+interface IInsertBeforeOperation {
+    kind: 'insert-before';
+    anchor: string;
+    snippet: string;
+    ifMissing?: string;
+    description?: string;
+}
+interface IReplaceOperation {
+    kind: 'replace';
+    /** Literal substring to find. */
+    find: string;
+    /** Replacement text. */
+    replaceWith: string;
+    /**
+     * If provided, the engine requires exactly this many matches; otherwise the
+     * default is exactly 1. Multiple matches without an explicit `expectMatches`
+     * is a conflict (ambiguous replace).
+     */
+    expectMatches?: number;
+    description?: string;
+}
+interface IExportOperation {
+    kind: 'export';
+    /** The symbol/path to re-export. */
+    from: string;
+    /** Optional named symbols. When omitted, emits `export * from`. */
+    symbols?: readonly string[];
+    /** Idempotency check; default = computed export line. */
+    ifMissing?: string;
+    description?: string;
+}
+interface IEnsureImportOperation {
+    kind: 'ensure-import';
+    /** Module specifier, e.g. `'./events'` or `'@app/plugin-core'`. */
+    from: string;
+    /**
+     * Named symbols to ensure. The op is a NO-OP for symbols already imported
+     * from `from`. Default import (`type: 'default'`) and namespace import
+     * (`type: 'namespace'`) are also supported via dedicated fields below.
+     */
+    symbols?: readonly string[];
+    /** Treat the import as `import type { ... }` instead of value import. */
+    typeOnly?: boolean;
+    /** Default import binding (e.g. `import Foo from 'foo'`). */
+    defaultBinding?: string;
+    /** Namespace import binding (e.g. `import * as foo from 'foo'`). */
+    namespaceBinding?: string;
+    description?: string;
+}
+interface IInsertEnumEntryOperation {
+    kind: 'insert-enum-entry';
+    /** Enum identifier, e.g. `PaginationEventType`. */
+    enumName: string;
+    /** Identifier of the new enum member, e.g. `ITEM_SELECTED`. */
+    entryName: string;
+    /** Literal string value to assign, e.g. `'pagination.itemSelected'`. */
+    entryValue: string;
+    description?: string;
+}
+interface IInsertObjectEntryOperation {
+    kind: 'insert-object-entry';
+    /** Object identifier, e.g. `FEATURE_KEYS`. */
+    objectName: string;
+    /** Key to add. */
+    entryKey: string;
+    /** Value literal (already source-formatted). */
+    entryValue: string;
+    /** When `true`, allow shorthand entries; default `false`. */
+    shorthand?: boolean;
+    description?: string;
+}
+interface IInsertBeforeClosingBraceOperation {
+    kind: 'insert-before-closing-brace';
+    /** Container identifier, e.g. an interface/class/enum name. */
+    containerName: string;
+    /** Snippet inserted immediately before the matching closing brace. */
+    snippet: string;
+    /** Optional idempotency marker (default = `snippet`). */
+    ifMissing?: string;
+    description?: string;
+}
+interface IInsertBetweenAnchorsOperation {
+    kind: 'insert-between-anchors';
+    beginAnchor: string;
+    endAnchor: string;
+    snippet: string;
+    /** Optional idempotency marker (default = `snippet`). */
+    ifMissing?: string;
+    description?: string;
+}
+export type IPlannedOperation = ICreateOperation | IAppendOperation | IInsertAfterOperation | IInsertBeforeOperation | IReplaceOperation | IExportOperation | IEnsureImportOperation | IInsertEnumEntryOperation | IInsertObjectEntryOperation | IInsertBeforeClosingBraceOperation | IInsertBetweenAnchorsOperation;
+export interface IPlannedChange {
+    /** Final file path relative to project root. */
+    targetPath: string;
+    /** Operation intent. */
+    operation: IPlannedOperation;
+}
+export interface IEvaluateInput {
+    change: IPlannedChange;
+    absolutePath: string;
+    relativePath: string;
+    /** Contents of the existing target file, or `null` if the file is absent. */
+    existing: string | null;
+}
+export declare function evaluatePlannedChange(input: IEvaluateInput): IFileChange;
+/**
+ * True if a change kind is an UPDATE-like operation (writes to an existing
+ * file via a structural mutation). CREATE/Skip/Conflict/legacy-Update are not
+ * update-like in the v2 sense.
+ */
+export declare function isUpdateLike(type: FileChangeType): boolean;
+export {};
+//# sourceMappingURL=planned-change.d.ts.map

package/dist/planned-change.d.ts.map

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