@shrkcrft/cli 0.1.0-alpha.2

package/dist/asset-preview/apply-template-update.js

@@ -0,0 +1,257 @@
+/**
+ * Templates update apply splicer.
+ *
+ * Mutates an existing template literal in place by replacing or inserting
+ * top-level fields. Used by `shrk templates update --apply`.
+ *
+ * Supported top-level fields:
+ *   - `name`, `description` (scalar strings)
+ *   - `tags`, `scope`, `appliesWhen`, `related` (string arrays)
+ *
+ * Array merge modes:
+ *   - Array fields accept `{ mode: 'add' | 'remove' | 'set', values }`. A
+ *     bare array is treated as `{ mode: 'set', values }` for back-compat.
+ *     `add` merges (dedupe, preserve original order, append new),
+ *     `remove` drops matching values, `set` is wholesale replace.
+ *   - `metadata.*` nested merge. Known scalar fields (booleans,
+ *     numbers, strings) replace; known string-array fields
+ *     (`requiredAnchors`, `requiredProfileIds`, `forbiddenPathFragments`,
+ *     `requiredVerificationCommandIds`) accept add/remove/set the same
+ *     way top-level arrays do.
+ *
+ * Refused:
+ *   - `files`, `changes`, `targetPath`, `content` — function resolvers.
+ *   - `variables` — structural, not a simple replacement target.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { findEntryRange, findNestedObjectRange, readStringArrayField, upsertScalarField, } from "./entry-mutator.js";
+function normaliseArrayOp(op) {
+    if (Array.isArray(op))
+        return { mode: 'set', values: op };
+    const o = op;
+    return { mode: o.mode, values: o.values };
+}
+function mergeArray(current, op) {
+    if (op.mode === 'set')
+        return op.values;
+    const base = current ?? [];
+    if (op.mode === 'add') {
+        const set = new Set(base);
+        const out = [...base];
+        for (const v of op.values) {
+            if (!set.has(v)) {
+                out.push(v);
+                set.add(v);
+            }
+        }
+        return out;
+    }
+    // mode === 'remove'
+    const removeSet = new Set(op.values);
+    return base.filter((v) => !removeSet.has(v));
+}
+function escapesCwd(cwd, absPath) {
+    const rel = nodePath.relative(cwd, absPath);
+    return rel.startsWith('..') || nodePath.isAbsolute(rel);
+}
+function buildUnifiedDiff(rel, a, b) {
+    const aLines = a.split('\n');
+    const bLines = b.split('\n');
+    let prefix = 0;
+    while (prefix < aLines.length && prefix < bLines.length && aLines[prefix] === bLines[prefix]) {
+        prefix += 1;
+    }
+    let suffix = 0;
+    while (suffix < aLines.length - prefix &&
+        suffix < bLines.length - prefix &&
+        aLines[aLines.length - 1 - suffix] === bLines[bLines.length - 1 - suffix]) {
+        suffix += 1;
+    }
+    const aMid = aLines.slice(prefix, aLines.length - suffix);
+    const bMid = bLines.slice(prefix, bLines.length - suffix);
+    const head = `--- ${rel}\n+++ ${rel}\n@@ -${prefix + 1},${aMid.length} +${prefix + 1},${bMid.length} @@\n`;
+    return (head +
+        aMid.map((l) => `-${l}`).join('\n') +
+        (aMid.length ? '\n' : '') +
+        bMid.map((l) => `+${l}`).join('\n'));
+}
+export function applyTemplateUpdate(input) {
+    const cwd = nodePath.resolve(input.cwd);
+    const targetAbs = nodePath.resolve(cwd, input.targetPath);
+    if (escapesCwd(cwd, targetAbs)) {
+        return {
+            ok: false,
+            refusal: `Target path escapes the project root (cwd=${cwd}).`,
+            targetAbs,
+            templateId: input.templateId,
+            originalLength: 0,
+            nextLength: 0,
+            fieldChanges: [],
+            wrote: false,
+        };
+    }
+    if (!existsSync(targetAbs)) {
+        return {
+            ok: false,
+            refusal: `Target file not found: ${targetAbs}`,
+            targetAbs,
+            templateId: input.templateId,
+            originalLength: 0,
+            nextLength: 0,
+            fieldChanges: [],
+            wrote: false,
+        };
+    }
+    const body = readFileSync(targetAbs, 'utf8');
+    let workingBody = body;
+    let range = findEntryRange(workingBody, input.templateId);
+    if (!range) {
+        return {
+            ok: false,
+            refusal: `Template "${input.templateId}" not found in ${nodePath.relative(cwd, targetAbs)}.`,
+            targetAbs,
+            templateId: input.templateId,
+            originalLength: body.length,
+            nextLength: body.length,
+            fieldChanges: [],
+            wrote: false,
+        };
+    }
+    const fieldChanges = [];
+    function applyScalar(field, value) {
+        const literal = JSON.stringify(value);
+        const fragment = `${field}: ${literal},`;
+        const result = upsertScalarField(workingBody, range, field, literal, fragment);
+        workingBody = result.body;
+        range = findEntryRange(workingBody, input.templateId);
+        if (range)
+            fieldChanges.push({ field, mode: result.mode });
+    }
+    function applyArray(field, op) {
+        const norm = normaliseArrayOp(op);
+        const current = readStringArrayField(workingBody, range, field);
+        const next = mergeArray(current, norm);
+        const literal = JSON.stringify(next);
+        const fragment = `${field}: ${literal},`;
+        const result = upsertScalarField(workingBody, range, field, literal, fragment);
+        workingBody = result.body;
+        range = findEntryRange(workingBody, input.templateId);
+        if (range)
+            fieldChanges.push({ field, mode: result.mode, arrayMode: norm.mode });
+    }
+    function applyMetadataArray(parentRange, field, op) {
+        const norm = normaliseArrayOp(op);
+        const current = readStringArrayField(workingBody, parentRange, field);
+        const next = mergeArray(current, norm);
+        const literal = JSON.stringify(next);
+        const fragment = `${field}: ${literal},`;
+        const result = upsertScalarField(workingBody, parentRange, field, literal, fragment);
+        workingBody = result.body;
+        const reroot = findEntryRange(workingBody, input.templateId);
+        if (!reroot)
+            return null;
+        const next1 = findNestedObjectRange(workingBody, reroot, 'metadata');
+        if (next1)
+            fieldChanges.push({ field: `metadata.${field}`, mode: result.mode, arrayMode: norm.mode });
+        return next1;
+    }
+    function applyMetadataScalar(parentRange, field, value) {
+        const literal = JSON.stringify(value);
+        const fragment = `${field}: ${literal},`;
+        const result = upsertScalarField(workingBody, parentRange, field, literal, fragment);
+        workingBody = result.body;
+        const reroot = findEntryRange(workingBody, input.templateId);
+        if (!reroot)
+            return null;
+        const next1 = findNestedObjectRange(workingBody, reroot, 'metadata');
+        if (next1)
+            fieldChanges.push({ field: `metadata.${field}`, mode: result.mode });
+        return next1;
+    }
+    if (input.fields.name !== undefined)
+        applyScalar('name', input.fields.name);
+    if (input.fields.description !== undefined)
+        applyScalar('description', input.fields.description);
+    if (input.fields.tags !== undefined)
+        applyArray('tags', input.fields.tags);
+    if (input.fields.scope !== undefined)
+        applyArray('scope', input.fields.scope);
+    if (input.fields.appliesWhen !== undefined)
+        applyArray('appliesWhen', input.fields.appliesWhen);
+    if (input.fields.related !== undefined)
+        applyArray('related', input.fields.related);
+    if (input.fields.metadata && range) {
+        // Insert a stub metadata block if absent so the nested merge has a
+        // landing pad. The stub is empty `{}` so subsequent upserts add fields.
+        let metadataRange = findNestedObjectRange(workingBody, range, 'metadata');
+        if (!metadataRange) {
+            const stub = 'metadata: {},';
+            const result = upsertScalarField(workingBody, range, 'metadata', '{}', stub);
+            workingBody = result.body;
+            range = findEntryRange(workingBody, input.templateId);
+            if (range) {
+                metadataRange = findNestedObjectRange(workingBody, range, 'metadata');
+                if (metadataRange) {
+                    fieldChanges.push({ field: 'metadata', mode: result.mode });
+                }
+            }
+        }
+        if (metadataRange) {
+            const meta = input.fields.metadata;
+            // Scalar fields first (order is deterministic so diffs are stable).
+            const scalarKeys = ['priority', 'maturity', 'dryRunOnly', 'requiresApproval'];
+            for (const key of scalarKeys) {
+                const v = meta[key];
+                if (v !== undefined) {
+                    const next = applyMetadataScalar(metadataRange, key, v);
+                    if (next)
+                        metadataRange = next;
+                }
+            }
+            const arrayKeys = [
+                'requiredAnchors',
+                'requiredProfileIds',
+                'forbiddenPathFragments',
+                'requiredVerificationCommandIds',
+            ];
+            for (const key of arrayKeys) {
+                const op = meta[key];
+                if (op !== undefined) {
+                    const next = applyMetadataArray(metadataRange, key, op);
+                    if (next)
+                        metadataRange = next;
+                }
+            }
+        }
+    }
+    if (fieldChanges.length === 0) {
+        return {
+            ok: false,
+            refusal: `No supported fields to apply for "${input.templateId}". Supported: name, description, tags, scope, appliesWhen, related, metadata.{priority, maturity, dryRunOnly, requiresApproval, requiredAnchors, requiredProfileIds, forbiddenPathFragments, requiredVerificationCommandIds}.`,
+            targetAbs,
+            templateId: input.templateId,
+            originalLength: body.length,
+            nextLength: body.length,
+            fieldChanges: [],
+            wrote: false,
+        };
+    }
+    let wrote = false;
+    if (input.write && workingBody !== body) {
+        writeFileSync(targetAbs, workingBody, 'utf8');
+        wrote = true;
+    }
+    const rel = nodePath.relative(cwd, targetAbs) || nodePath.basename(targetAbs);
+    const diff = buildUnifiedDiff(rel, body, workingBody);
+    return {
+        ok: true,
+        targetAbs,
+        templateId: input.templateId,
+        originalLength: body.length,
+        nextLength: workingBody.length,
+        fieldChanges,
+        diff,
+        wrote,
+    };
+}

package/dist/asset-preview/entry-mutator.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared entry-aware mutation primitives.
+ *
+ * Three apply paths (knowledge-stale, template-drift, templates-update)
+ * all need the same primitive: find an object literal by `id`, walk to
+ * its `{...}` range, then replace / insert / remove fields inside.
+ *
+ * Pure functions over file text. No IO. No inspector imports — operates
+ * on raw TS source.
+ */
+export interface IEntryRange {
+    /** Position of the opening `{` of the entry literal. */
+    readonly open: number;
+    /** Position of the matching closing `}`. */
+    readonly close: number;
+    /** Leading whitespace of the line containing the closing `}`. */
+    readonly indent: string;
+}
+/**
+ * Locate `{...}` range for an entry whose `id: '<id>'` appears in body.
+ * Returns null when not found.
+ *
+ * Heuristic: locate the `id: 'entryId'` line (single or double quotes),
+ * walk backwards to the nearest `{`, then walk forwards counting `{`/`}`
+ * with string-literal awareness so braces inside strings don't unbalance
+ * the count.
+ */
+export declare function findEntryRange(body: string, entryId: string): IEntryRange | null;
+/** True if the entry literal already declares a top-level field. */
+export declare function entryHasField(body: string, range: IEntryRange, fieldName: string): boolean;
+/**
+ * Insert a top-level field (TS source fragment) just before the closing
+ * `}` of the entry literal. Indents the fragment to match the entry.
+ *
+ * The caller is responsible for ensuring `body[range.close] === '}'`.
+ *
+ * The inserted line ends with `\n + range.indent` so the closing `}`
+ * re-lands on a properly indented line. `after` is preserved
+ * verbatim — slicing the indent off here would strip the closing
+ * `}` whenever it lived on its own indented line.
+ */
+export declare function insertField(body: string, range: IEntryRange, fieldFragment: string): string;
+/**
+ * Replace the value of a top-level scalar field inside the entry.
+ * Matches `<fieldName>: <value>,` (single-line) and replaces the value.
+ *
+ * Returns `null` when the field isn't present or isn't single-line.
+ */
+export declare function replaceScalarField(body: string, range: IEntryRange, fieldName: string, newLiteral: string): string | null;
+/**
+ * Upsert: replace the field if present (single-line scalar), insert
+ * otherwise. `fragmentForInsert` is the full `fieldName: value,` line
+ * used when the field is absent. `newLiteralForReplace` is the value
+ * portion used when the field is present.
+ */
+export declare function upsertScalarField(body: string, range: IEntryRange, fieldName: string, newLiteralForReplace: string, fragmentForInsert: string): {
+    body: string;
+    mode: 'replace' | 'insert';
+};
+/**
+ * Remove an element from a top-level array field by predicate on the
+ * raw element text. The array is parsed shallowly — elements are split
+ * at top-level commas (not inside nested `{}` / `[]` / strings).
+ *
+ * Returns `{ body, removedCount }`. Refuses (returns null) if the field
+ * isn't a single-line OR brace-delimited array. Idempotent — calling
+ * twice removes nothing on the second pass.
+ */
+export declare function removeArrayEntries(body: string, range: IEntryRange, fieldName: string, predicate: (element: string) => boolean): {
+    body: string;
+    removedCount: number;
+} | null;
+/**
+ * Remove an element from a top-level array of strings by exact value.
+ * Convenience wrapper over `removeArrayEntries`.
+ */
+export declare function removeStringFromArray(body: string, range: IEntryRange, fieldName: string, value: string): {
+    body: string;
+    removedCount: number;
+} | null;
+/**
+ * Find the `{...}` range of a nested object literal addressed by
+ * `<fieldName>: {` within the enclosing entry range. Returns null when
+ * the field is missing OR is not an object literal.
+ *
+ * Used by templates-update --apply to merge into `metadata.*` without
+ * touching the surrounding entry.
+ */
+export declare function findNestedObjectRange(body: string, parentRange: IEntryRange, fieldName: string): IEntryRange | null;
+/**
+ * Read a top-level string array field's current values from the
+ * entry literal. Returns the unquoted string values in source order, or
+ * null when the field isn't a single-line OR brace-delimited array.
+ *
+ * Tolerates nested string-quoted commas and surrounding whitespace.
+ * Used by templates-update --apply for `--add-tag` / `--remove-tag`
+ * merge math.
+ */
+export declare function readStringArrayField(body: string, range: IEntryRange, fieldName: string): readonly string[] | null;
+/**
+ * Split a comma-separated string at top-level commas (not inside
+ * strings or nested brackets). Preserves the original spacing inside
+ * each element so the caller can decide how to re-render.
+ */
+export declare function splitTopLevelCommas(inner: string): string[];
+//# sourceMappingURL=entry-mutator.d.ts.map

package/dist/asset-preview/entry-mutator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-mutator.d.ts","sourceRoot":"","sources":["../../src/asset-preview/entry-mutator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAuDhF;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAI1F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,CAkBR;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAaf;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,oBAAoB,EAAE,MAAM,EAC5B,iBAAiB,EAAE,MAAM,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAS9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,GACtC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA+E/C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQ/C;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,GAChB,WAAW,GAAG,IAAI,CA+CpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,GAChB,SAAS,MAAM,EAAE,GAAG,IAAI,CAmD1B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiC3D"}