@shrkcrft/generator 0.1.0-alpha.3 → 0.1.0-alpha.31

package/dist/planned-operation-fields.js

@@ -0,0 +1,100 @@
+export const PLANNED_OPERATION_FIELDS = {
+    create: { required: ['content'], optional: ['description'] },
+    append: { required: ['snippet'], optional: ['ifMissing', 'description'] },
+    'insert-after': { required: ['anchor', 'snippet'], optional: ['ifMissing', 'description'] },
+    'insert-before': { required: ['anchor', 'snippet'], optional: ['ifMissing', 'description'] },
+    replace: { required: ['find', 'replaceWith'], optional: ['expectMatches', 'description'] },
+    export: { required: ['from'], optional: ['symbols', 'ifMissing', 'description'] },
+    'ensure-import': {
+        required: ['from'],
+        optional: ['symbols', 'typeOnly', 'defaultBinding', 'namespaceBinding', 'description'],
+    },
+    'insert-enum-entry': { required: ['enumName', 'entryName', 'entryValue'], optional: ['description'] },
+    'insert-object-entry': {
+        required: ['objectName', 'entryKey', 'entryValue'],
+        optional: ['shorthand', 'description'],
+    },
+    'insert-array-entry': {
+        required: ['arrayName', 'entryValue'],
+        optional: ['arrayNameAlternatives', 'manualStepInstruction', 'ifMissing', 'description'],
+    },
+    'insert-before-closing-brace': {
+        required: ['containerName', 'snippet'],
+        optional: ['ifMissing', 'description'],
+    },
+    'insert-between-anchors': {
+        required: ['beginAnchor', 'endAnchor', 'snippet'],
+        optional: ['ifMissing', 'description'],
+    },
+};
+/** Explicit near-misses authors write for a required field. */
+const NEAR_MISS = {
+    key: ['entryKey'],
+    value: ['entryValue', 'snippet', 'content'],
+    name: ['entryName', 'arrayName', 'objectName', 'enumName', 'containerName'],
+    body: ['content', 'snippet'],
+    text: ['snippet', 'content'],
+    code: ['snippet', 'content'],
+    snippet: ['content'],
+    content: ['snippet'],
+    replace: ['replaceWith'],
+    with: ['replaceWith'],
+    search: ['find'],
+    pattern: ['find'],
+    begin: ['beginAnchor'],
+    end: ['endAnchor'],
+    target: ['arrayName', 'objectName', 'enumName', 'containerName'],
+};
+function isPresent(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return true;
+    return true;
+}
+/**
+ * Check one rendered op against the table. `kindKnown: false` means the kind is
+ * not a planned-operation kind at all; `missing` lists required fields that are
+ * absent; `unknown` lists keys the evaluator would silently drop; `suggestions`
+ * pairs an unknown key with the missing field it most likely meant
+ * (`value→entryValue`).
+ */
+export function validatePlannedOperation(op) {
+    if (!op || typeof op !== 'object') {
+        return { kindKnown: false, kind: String(op), missing: [], unknown: [], suggestions: [] };
+    }
+    const record = op;
+    const kind = typeof record.kind === 'string' ? record.kind : String(record.kind);
+    const spec = PLANNED_OPERATION_FIELDS[kind];
+    if (!spec)
+        return { kindKnown: false, kind, missing: [], unknown: [], suggestions: [] };
+    const missing = spec.required.filter((f) => !isPresent(record[f]));
+    const allowed = new Set(['kind', ...spec.required, ...spec.optional]);
+    const unknown = Object.keys(record).filter((k) => !allowed.has(k));
+    const suggestions = [];
+    for (const u of unknown) {
+        const explicit = (NEAR_MISS[u.toLowerCase()] ?? []).filter((f) => missing.includes(f));
+        const contained = missing.filter((f) => !explicit.includes(f) && f.toLowerCase().includes(u.toLowerCase()) && u.length >= 3);
+        const target = explicit[0] ?? contained[0];
+        if (target)
+            suggestions.push(`${u}→${target}`);
+    }
+    return { kindKnown: true, kind, missing, unknown, suggestions };
+}
+/**
+ * One sentence naming what is wrong with an op, or `undefined` when the op is
+ * well-formed (unknown extra keys alone are reported by the caller as a
+ * warning, not here).
+ */
+export function describeInvalidPlannedOperation(shape, where) {
+    if (!shape.kindKnown) {
+        return `${where}: unknown operation kind "${shape.kind}" — must be one of ${Object.keys(PLANNED_OPERATION_FIELDS).join(', ')}`;
+    }
+    if (shape.missing.length === 0)
+        return undefined;
+    const parts = [`missing required ${shape.missing.join(', ')}`];
+    if (shape.unknown.length > 0)
+        parts.push(`unknown keys ${shape.unknown.join(', ')}`);
+    const hint = shape.suggestions.length > 0 ? ` — did you mean ${shape.suggestions.join(', ')}?` : '';
+    return `${where} (${shape.kind}): ${parts.join('; ')}${hint}`;
+}

package/dist/saved-plan.d.ts

@@ -12,6 +12,24 @@ export interface ISavedPlanExpectedChange {
     type: string;
     relativePath: string;
     sizeBytes: number;
+    /**
+     * SHA-256 hex digest of the exact rendered body that `gen --print` shows.
+     * Always emitted by `buildSavedPlan`; may be absent on legacy plans written
+     * before body/digest persistence. The plan is the review/apply artifact, so
+     * this digest lets a later review or apply verify — WITHOUT re-rendering —
+     * that the live content still matches what was previewed. Covered by the
+     * HMAC signature (canonical JSON includes the whole `expectedChanges`).
+     */
+    sha256?: string;
+    /**
+     * The exact rendered file body that would be written — byte-identical to
+     * what `gen --print` / `--show-content` displays. Embedded so the saved
+     * plan carries enough to be reviewed for correctness, diffed against HEAD,
+     * and re-applied deterministically instead of storing only a byte count.
+     * Always emitted by `buildSavedPlan`; may be absent on legacy plans. Covered
+     * by the HMAC signature.
+     */
+    body?: string;
     /**
      * v2-only — the operation intent that produced this change. Present iff
      * the schema is `sharkcraft.plan/v2`. Tampering with this field invalidates
@@ -87,12 +105,20 @@ export interface BuildSavedPlanInput {
  * resulting plan is tagged `sharkcraft.plan/v2`; otherwise v1.
  */
 export declare function buildSavedPlan(input: BuildSavedPlanInput): ISavedPlan;
+/** SHA-256 hex digest of a rendered file body (UTF-8). */
+export declare function sha256Hex(body: string): string;
 export declare function savePlanToFile(plan: ISavedPlan, filePath: string): Result<void, AppError>;
 export declare function readPlanFromFile(filePath: string): Result<ISavedPlan, AppError>;
 export interface IPlanDiff {
     relativePath: string;
-    /** "added" | "removed" | "type-changed" | "size-changed" | "operation-changed" */
-    kind: 'added' | 'removed' | 'type-changed' | 'size-changed' | 'operation-changed';
+    /**
+     * "added" | "removed" | "type-changed" | "size-changed" |
+     * "operation-changed" | "content-changed". `content-changed` fires when the
+     * live body's digest differs from the saved `sha256` even though the byte
+     * count matches — a same-size content edit that a size check alone would
+     * miss.
+     */
+    kind: 'added' | 'removed' | 'type-changed' | 'size-changed' | 'operation-changed' | 'content-changed';
     detail?: string;
 }
 /**

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

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

package/dist/saved-plan.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
 /** v1 schema marker — kept for legacy CREATE-only plans. */
 export const SAVED_PLAN_SCHEMA_V1 = 'sharkcraft.plan/v1';
@@ -20,6 +21,11 @@ export function buildSavedPlan(input) {
             type: String(c.type),
             relativePath: c.relativePath,
             sizeBytes: c.sizeBytes,
+            // Persist the exact rendered body (what `--print` shows) plus its
+            // digest, so the saved plan IS the reviewable / re-appliable artifact
+            // rather than a bare byte count. Both are covered by the HMAC signature.
+            sha256: sha256Hex(c.contents),
+            body: c.contents,
         };
         if (c.operation !== undefined)
             entry.operation = c.operation;
@@ -41,6 +47,10 @@ export function buildSavedPlan(input) {
         out.folderOps = [...input.folderOps];
     return out;
 }
+/** SHA-256 hex digest of a rendered file body (UTF-8). */
+export function sha256Hex(body) {
+    return createHash('sha256').update(body, 'utf8').digest('hex');
+}
 export function savePlanToFile(plan, filePath) {
     try {
         mkdirSync(dirname(filePath), { recursive: true });
@@ -202,6 +212,16 @@ export function diffPlanChanges(saved, fresh) {
                 detail: `${expected.sizeBytes}B → ${actual.sizeBytes}B`,
             });
         }
+        else if (expected.sha256 !== undefined &&
+            sha256Hex(actual.contents) !== expected.sha256) {
+            // Same byte count, different bytes: only the persisted digest catches
+            // this. Legacy plans without `sha256` skip the check (size-only).
+            out.push({
+                relativePath: expected.relativePath,
+                kind: 'content-changed',
+                detail: 'body digest mismatch (same size, different content)',
+            });
+        }
     }
     for (const [key, actual] of freshByKey) {
         if (!expectedByKey.has(key)) {

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

@@ -1 +1 @@
-{"version":3,"file":"synthetic-plan.d.ts","sourceRoot":"","sources":["../src/synthetic-plan.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,MAAM,GAClB,eAAe,CAsCjB;AAuBD,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,GACpB,MAAM,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAsCzC"}
+{"version":3,"file":"synthetic-plan.d.ts","sourceRoot":"","sources":["../src/synthetic-plan.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,MAAM,GAClB,eAAe,CA8CjB;AAoDD,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAWD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,GACpB,MAAM,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAmEzC"}

package/dist/synthetic-plan.js

@@ -15,6 +15,7 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { safeResolveTargetPath } from '@shrkcrft/core';
 import { evaluatePlannedChange } from "./planned-change.js";
 import { FileChangeType } from "./file-change.js";
 export const SYNTHETIC_TEMPLATE_PREFIX = '__';
@@ -26,6 +27,14 @@ export function evaluateSavedPlanInPlace(plan, projectRoot) {
     const warnings = [];
     let hasConflicts = false;
     const expected = plan.expectedChanges ?? [];
+    // Per-file content overlay so MULTIPLE ops on the SAME file COMPOSE: each op
+    // sees the cumulative result of the prior ops on that path rather than the
+    // original on-disk bytes. Mirrors the template path in dry-run.ts. Without
+    // it, [append A, append B] loses A (the writer's last same-path write
+    // clobbers earlier ones) and create-then-modify on one NEW path
+    // false-conflicts (op2 reads stale disk). Keyed by absolute path → the
+    // cumulative content after the prior op(s).
+    const overlay = new Map();
     for (const e of expected) {
         if (!e.operation) {
             // Without an operation we cannot reconstruct contents — surface as
@@ -42,7 +51,7 @@ export function evaluateSavedPlanInPlace(plan, projectRoot) {
             hasConflicts = true;
             continue;
         }
-        const change = applyOperation(projectRoot, e.relativePath, e.operation);
+        const change = applyOperation(projectRoot, e.relativePath, e.operation, overlay);
         if (change.type === FileChangeType.Conflict)
             hasConflicts = true;
         changes.push(change);
@@ -61,15 +70,44 @@ export function evaluateSavedPlanInPlace(plan, projectRoot) {
     }
     return out;
 }
-function applyOperation(projectRoot, relativePath, operation) {
-    const absolutePath = nodePath.resolve(projectRoot, relativePath);
-    const existing = existsSync(absolutePath) ? readFileSync(absolutePath, 'utf8') : null;
-    return evaluatePlannedChange({
-        change: { targetPath: relativePath, operation },
-        absolutePath,
-        relativePath,
+function applyOperation(projectRoot, relativePath, operation, overlay) {
+    // Route through the single generator chokepoint instead of a bare resolve, so
+    // a traversal / absolute `relativePath` in a hand-crafted or tampered plan
+    // can't write OUTSIDE the project root. An unsafe path becomes a Conflict,
+    // which writeSyntheticPlan refuses (matching the template path in dry-run.ts).
+    let safe;
+    try {
+        safe = safeResolveTargetPath(relativePath, projectRoot);
+    }
+    catch (e) {
+        const pathErr = e;
+        return {
+            type: FileChangeType.Conflict,
+            absolutePath: pathErr.rawPath,
+            relativePath: pathErr.rawPath,
+            contents: '',
+            reason: `Refused unsafe target path (${pathErr.code}): ${pathErr.message}`,
+            sizeBytes: 0,
+        };
+    }
+    // Prefer the overlay (the cumulative result of prior same-file ops) over the
+    // on-disk bytes so op N sees the result of ops 1..N-1. Falls back to the live
+    // file, then to absent (`null`) for a brand-new path.
+    const existing = overlay.has(safe.absolutePath)
+        ? (overlay.get(safe.absolutePath) ?? null)
+        : existsSync(safe.absolutePath)
+            ? readFileSync(safe.absolutePath, 'utf8')
+            : null;
+    const result = evaluatePlannedChange({
+        change: { targetPath: safe.relativePath, operation },
+        absolutePath: safe.absolutePath,
+        relativePath: safe.relativePath,
         existing,
     });
+    // Record the cumulative content (Skip/Conflict carry the unchanged bytes,
+    // which is exactly what a later op on the same file should see).
+    overlay.set(safe.absolutePath, result.contents);
+    return result;
 }
 /**
  * Write evaluated changes from a synthetic plan directly. The caller
@@ -78,30 +116,63 @@ function applyOperation(projectRoot, relativePath, operation) {
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+/**
+ * A CCR retrieval marker (`<<ccr:<hex>…>>`) is a pointer into the compress
+ * cache — a LOSSY/compressed view, never apply-grade source. If one ever
+ * reaches a write (e.g. a compressed diff fed into a `create`/`replace` op), it
+ * would corrupt the file. This detector enforces, at the write chokepoint, the
+ * invariant that the compression layer only documents in a comment.
+ */
+const CCR_MARKER_RE = /<<ccr:[0-9a-f]{8,}/;
 export function writeSyntheticPlan(plan) {
     if (plan.hasConflicts) {
         return err(new AppErrorImpl(ERROR_CODES.TARGET_FILE_EXISTS, 'Synthetic plan refused: conflicts present', { details: { conflicts: plan.changes.filter((c) => c.type === FileChangeType.Conflict) } }));
     }
-    const written = [];
-    let totalBytes = 0;
-    let skipped = 0;
+    // Refuse the WHOLE plan if any writeable change carries a CCR marker — a
+    // compressed/lossy blob must never be written as source.
     for (const change of plan.changes) {
-        if (change.type === FileChangeType.Skip) {
-            skipped += 1;
-            continue;
-        }
         if (!isWriteableSyntheticChange(change.type))
             continue;
+        if (CCR_MARKER_RE.test(change.contents)) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Refused to write ${change.relativePath}: contents carry a <<ccr:…>> marker (a compressed/lossy blob is not apply-grade source).`, { details: { path: change.relativePath } }));
+        }
+    }
+    // Compose multiple ops on the SAME path into ONE write. `evaluateSavedPlanInPlace`
+    // threads an overlay, so the LAST writeable change for a path already carries
+    // the cumulative result of every prior same-path op (any trailing Skip leaves
+    // those bytes unchanged). Writing that once — instead of every op's contents
+    // in order, last-write-wins — avoids redundant writes and keeps the success
+    // count honest: `written` and `summary.written` count DISTINCT paths.
+    const lastWriteableByPath = new Map();
+    const skipPaths = new Set();
+    for (const change of plan.changes) {
+        if (isWriteableSyntheticChange(change.type)) {
+            lastWriteableByPath.set(change.absolutePath, change);
+        }
+        else if (change.type === FileChangeType.Skip) {
+            skipPaths.add(change.absolutePath);
+        }
+    }
+    const written = [];
+    let totalBytes = 0;
+    for (const [absolutePath, change] of lastWriteableByPath) {
         try {
-            mkdirSync(nodePath.dirname(change.absolutePath), { recursive: true });
-            writeFileSync(change.absolutePath, change.contents, 'utf8');
+            mkdirSync(nodePath.dirname(absolutePath), { recursive: true });
+            writeFileSync(absolutePath, change.contents, 'utf8');
             written.push(change);
             totalBytes += change.sizeBytes;
         }
         catch (e) {
-            return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, `Failed to write ${change.absolutePath}`, { details: { path: change.absolutePath }, cause: e }));
+            return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, `Failed to write ${absolutePath}`, { details: { path: absolutePath }, cause: e }));
         }
     }
+    // A path counts as skipped only when EVERY op on it resolved to Skip (a path
+    // that was also written is not a skip).
+    let skipped = 0;
+    for (const p of skipPaths) {
+        if (!lastWriteableByPath.has(p))
+            skipped += 1;
+    }
     return ok({
         summary: { written: written.length, skipped, conflicts: 0, totalBytes },
         written,

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shrkcrft/generator",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.31",
   "description": "SharkCraft plan-first generator: GenerationPlan, FileChange, dry-run, safe writes.",
   "license": "MIT",
   "author": "SharkCraft contributors",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -43,10 +43,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.2",
-    "@shrkcrft/templates": "^0.1.0-alpha.2",
-    "@shrkcrft/rules": "^0.1.0-alpha.2",
-    "@shrkcrft/paths": "^0.1.0-alpha.2"
+    "@shrkcrft/core": "^0.1.0-alpha.31",
+    "@shrkcrft/templates": "^0.1.0-alpha.31",
+    "@shrkcrft/rules": "^0.1.0-alpha.31",
+    "@shrkcrft/paths": "^0.1.0-alpha.31"
   },
   "publishConfig": {
     "access": "public"