@ngockhoale/ukit 1.2.2 → 1.3.0

package/templates/.claude/ukit/runtime/safe-patch-core.mjs

@@ -0,0 +1,140 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_SAFE_PATCH_CONFIG = {
+  enabled: true,
+  strictSharedRisk: true,
+  largeFileLineThreshold: 800,
+  largeFileByteThreshold: 200_000,
+  backupEnabled: true,
+  backupRetentionDays: 30,
+  deltaMaxChangedLines: 120,
+  deltaMaxHunks: 3,
+  deltaMaxDiffCells: 2_000_000,
+};
+
+const SHARED_RISK_PATTERNS = [
+  /^\.claude\/hooks\//,
+  /^\.claude\/ukit\//,
+  /^\.codex\//,
+  /^templates\/\.claude\/hooks\//,
+  /^templates\/\.claude\/ukit\//,
+  /^src\/index\//,
+  /^src\/core\/(runInstallPipeline|applyPlan|buildPlan|diffPlan|metadata|migrateLegacy|uninstall|runtimeConfig|runtimePaths)\.js$/,
+  /^src\/core\/(output|token|compact)\//,
+  /^manifests\/platform\.full\.yaml$/,
+  // Intentional for UKit development: template edits become installed runtime behavior after `ukit install`,
+  // so templates stay in the strict shared-risk lane rather than being treated as ordinary docs/assets.
+  /^templates\//,
+  /^scripts\//,
+  /(^|\/)(AGENTS|CLAUDE)\.md$/,
+];
+
+export function parseJsonInput(raw, fallback = {}) {
+  try {
+    return JSON.parse(String(raw || '').trim() || '{}');
+  } catch {
+    return fallback;
+  }
+}
+
+export async function readRuntimeSafePatchConfig(projectRoot) {
+  const configPath = path.join(projectRoot, '.ukit', 'storage', 'config.json');
+  try {
+    const raw = await fs.readFile(configPath, 'utf8');
+    const config = JSON.parse(raw);
+    return { ...DEFAULT_SAFE_PATCH_CONFIG, ...(config.safePatch && typeof config.safePatch === 'object' ? config.safePatch : {}) };
+  } catch {
+    return { ...DEFAULT_SAFE_PATCH_CONFIG };
+  }
+}
+
+export function normalizeRelativePath(value) {
+  return String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+export function resolveProjectFile(projectRoot, filePath) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const raw = String(filePath || '').trim();
+  if (!raw) return null;
+  const absolute = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(root, raw);
+  const relative = path.relative(root, absolute);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Path escapes project root: ${filePath}`);
+  }
+  return {
+    absolute,
+    relative: normalizeRelativePath(relative),
+  };
+}
+
+export async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function classifySafePatchRisk(relativePath, profile = null, config = DEFAULT_SAFE_PATCH_CONFIG) {
+  const normalized = normalizeRelativePath(relativePath);
+  const labels = [];
+  if (SHARED_RISK_PATTERNS.some((pattern) => pattern.test(normalized))) {
+    labels.push('shared-risk');
+  }
+  if (profile?.size > Number(config.largeFileByteThreshold || DEFAULT_SAFE_PATCH_CONFIG.largeFileByteThreshold)) {
+    labels.push('large-file');
+  }
+  if (profile?.text) {
+    const lines = profile.text.split(/\r\n|\n|\r/).length;
+    if (lines > Number(config.largeFileLineThreshold || DEFAULT_SAFE_PATCH_CONFIG.largeFileLineThreshold)) {
+      labels.push('large-file');
+    }
+  }
+  if (profile?.hasBom) labels.push('bom-sensitive');
+  if (profile?.newline === 'CRLF' || profile?.newline === 'CR' || profile?.newline === 'mixed') labels.push('newline-sensitive');
+  if (profile?.text && /[^\x00-\x7f]/.test(profile.text)) labels.push('multilingual-text');
+  if (profile?.shebangHasBom) labels.push('shebang-bom');
+  if (profile?.binaryLike || profile?.utf8Valid === false) labels.push('non-text');
+
+  return {
+    labels: [...new Set(labels)],
+    strict: labels.includes('shared-risk') || labels.includes('large-file') || labels.includes('shebang-bom'),
+  };
+}
+
+export function countOccurrences(text, needle) {
+  const haystack = String(text ?? '');
+  const query = String(needle ?? '');
+  if (!query) return { count: 0, indexes: [] };
+  const indexes = [];
+  let start = 0;
+  while (start <= haystack.length) {
+    const index = haystack.indexOf(query, start);
+    if (index === -1) break;
+    indexes.push(index);
+    start = index + Math.max(query.length, 1);
+  }
+  return { count: indexes.length, indexes };
+}
+
+export function lineNumberForIndex(text, index) {
+  return String(text ?? '').slice(0, Math.max(0, index)).split(/\n/).length;
+}
+
+export function buildLineWindow(text, line, contextLines = 3) {
+  const lines = String(text ?? '').split(/\r\n|\n|\r/);
+  const startLine = Math.max(1, Number(line || 1) - contextLines);
+  const endLine = Math.min(lines.length, Number(line || 1) + contextLines);
+  return {
+    startLine,
+    endLine,
+    text: lines.slice(startLine - 1, endLine).join('\n'),
+  };
+}
+
+export function summarizeSnippet(value, max = 240) {
+  const compact = String(value || '').replace(/\s+/g, ' ').trim();
+  return compact.length > max ? `${compact.slice(0, max - 3)}...` : compact;
+}

package/templates/.claude/ukit/runtime/text-profile.mjs

@@ -0,0 +1,139 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const UTF8_BOM = Buffer.from([0xef, 0xbb, 0xbf]);
+
+export function analyzeTextBuffer(buffer) {
+  const bytes = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer ?? '');
+  const hasBom = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+  const body = hasBom ? bytes.subarray(3) : bytes;
+  const sha256 = crypto.createHash('sha256').update(bytes).digest('hex');
+  const binaryLike = looksBinaryLike(body);
+
+  let text = '';
+  let utf8Valid = false;
+  let decodeError = null;
+  if (!binaryLike) {
+    try {
+      text = new TextDecoder('utf-8', { fatal: true }).decode(body);
+      utf8Valid = true;
+    } catch (error) {
+      decodeError = error?.message || String(error);
+    }
+  }
+
+  const newline = utf8Valid ? detectNewlineStyle(text) : 'unknown';
+  const hasFinalNewline = utf8Valid ? /(?:\r\n|\n|\r)$/.test(text) : false;
+  const shebangHasBom = hasBom && body.length >= 2 && body[0] === 0x23 && body[1] === 0x21;
+
+  return {
+    hasBom,
+    newline,
+    hasFinalNewline,
+    binaryLike,
+    utf8Valid,
+    sha256,
+    size: bytes.length,
+    text,
+    bodySize: body.length,
+    shebangHasBom,
+    ...(decodeError ? { decodeError } : {}),
+  };
+}
+
+export async function analyzeTextFile(filePath) {
+  const buffer = await fs.readFile(filePath);
+  return analyzeTextBuffer(buffer);
+}
+
+export function publicTextProfile(profile) {
+  return {
+    hasBom: Boolean(profile?.hasBom),
+    newline: profile?.newline ?? 'unknown',
+    hasFinalNewline: Boolean(profile?.hasFinalNewline),
+    binaryLike: Boolean(profile?.binaryLike),
+    utf8Valid: Boolean(profile?.utf8Valid),
+    sha256: profile?.sha256 ?? '',
+    size: Number(profile?.size ?? 0),
+    shebangHasBom: Boolean(profile?.shebangHasBom),
+  };
+}
+
+export function encodeTextWithProfile(text, profile = {}) {
+  const encoded = Buffer.from(String(text ?? ''), 'utf8');
+  return profile.hasBom ? Buffer.concat([UTF8_BOM, encoded]) : encoded;
+}
+
+export function normalizeNewlinesForProfile(text, profile = {}) {
+  const value = String(text ?? '');
+  if (profile.newline !== 'CRLF' && profile.newline !== 'CR') {
+    return value;
+  }
+
+  const normalized = value.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  if (profile.newline === 'CR') {
+    return normalized.replace(/\n/g, '\r');
+  }
+  return normalized.replace(/\n/g, '\r\n');
+}
+
+export async function writeTextWithProfile(filePath, text, profile = {}) {
+  await fs.writeFile(filePath, encodeTextWithProfile(text, profile));
+}
+
+function detectNewlineStyle(text) {
+  const crlf = (text.match(/\r\n/g) || []).length;
+  const bareLf = (text.match(/(?<!\r)\n/g) || []).length;
+  const bareCr = (text.match(/\r(?!\n)/g) || []).length;
+  const styles = [crlf > 0 ? 'CRLF' : null, bareLf > 0 ? 'LF' : null, bareCr > 0 ? 'CR' : null].filter(Boolean);
+  if (styles.length === 0) return 'none';
+  if (styles.length === 1) return styles[0];
+  return 'mixed';
+}
+
+function looksBinaryLike(buffer) {
+  if (!buffer || buffer.length === 0) return false;
+  const sample = buffer.subarray(0, Math.min(buffer.length, 4096));
+  let suspicious = 0;
+  for (const byte of sample) {
+    if (byte === 0) return true;
+    if (byte < 0x09) suspicious += 1;
+    if (byte > 0x0d && byte < 0x20) suspicious += 1;
+  }
+  return suspicious / sample.length > 0.15;
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = { json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') args.json = true;
+    else if (arg === '--file') args.file = argv[++i];
+    else if (arg === '--help' || arg === '-h') args.help = true;
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs();
+  if (args.help || !args.file) {
+    const help = 'Usage: node text-profile.mjs --file <path> [--json]';
+    process.stdout.write(args.json ? `${JSON.stringify({ help })}\n` : `${help}\n`);
+    return;
+  }
+  const profile = publicTextProfile(await analyzeTextFile(args.file));
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify({ profile })}\n`);
+  } else {
+    process.stdout.write(`[ukit:text-profile] ${args.file} bom=${profile.hasBom ? 'yes' : 'no'} newline=${profile.newline} utf8=${profile.utf8Valid ? 'valid' : 'invalid'} bytes=${profile.size}\n`);
+  }
+}
+
+if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
+  main().catch((error) => {
+    process.stderr.write(`[ukit:text-profile] ERROR: ${error?.message || error}\n`);
+    process.exit(1);
+  });
+}

package/templates/.codex/README.md

@@ -12,10 +12,10 @@ Auto-generated by UKit for OpenAI Codex.
 - Do not make end users memorize skill names, helper scripts, or routing internals unless they are debugging UKit itself.
 - **Treat helper commands as internal orchestration. Do not ask end users to run them.**
 
-## UKit v1.2.2 Shared Runtime
+## UKit v1.3.0 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
-- Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, and validation toggles.
+- Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, validation, and Safe Patch guardrail toggles.
 - Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening docs.
 - Reusable cache state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
@@ -24,6 +24,7 @@ Auto-generated by UKit for OpenAI Codex.
 - Reuse compact `previous-context` / `recent-output` route snapshots before replaying raw history.
 - Threshold-based compact pressure is internal orchestration; Codex users should not need to manage it manually.
 - UKit keeps Claude PreCompact/reinject and OpenCode native auto/prune compaction intact. For Codex Desktop long sessions, UKit can use `subagents.smallTaskModel` through `ukit-small-task-maintainer` to decide soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 app-context tokens.
+- Safe Patch Protocol is internal: for risky file edits, prefer current-file anchors and exact specs, avoid whole-file rewrites, and preserve multilingual/BOM/newline profiles. Do not ask normal users to run helper commands.
 
 ## Speed / Reading Contract
 

package/templates/AGENTS.md

@@ -43,10 +43,10 @@
 - If a concrete verification lane is needed, prefer `node .claude/ukit/index/verify-context.mjs ...`.
 - These helper/index commands are internal orchestration. Run them yourself when needed; never turn them into required end-user workflow.
 
-## UKit v1.2.2 Shared Runtime
+## UKit v1.3.0 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
-- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, and validation behavior.
+- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
 - Reuse `.ukit/storage/memory/` before asking users to restate prior decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
 - Reusable runtime cache lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, and `.ukit/storage/cache/output-history.json`.
@@ -95,6 +95,13 @@
 - If route memory already includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
 - Do not ask end users to name agents or remember agent commands.
 
+## Safe Patch Protocol
+
+- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
+- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files; use UKit safe patch helpers internally when normal Edit/Write may normalize bytes.
+
 ## Team Workflow Safety
 
 - Do not teach normal contributors `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they are explicitly debugging UKit itself.

package/templates/CLAUDE.md

@@ -42,10 +42,10 @@
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
 
-## UKit v1.2.2 Shared Runtime
+## UKit v1.3.0 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
-- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, and validation behavior.
+- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
 - Reuse `.ukit/storage/memory/` before asking users to restate decisions.
 - For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
 - Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, and `.ukit/storage/cache/output-history.json`.
@@ -53,6 +53,14 @@
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
 - If runtime files are missing or corrupt, tell maintainers to rerun `ukit install`.
 
+
+## Safe Patch Protocol
+
+- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
+- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
+- Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files; use UKit safe patch helpers internally when normal Edit/Write may normalize bytes.
+
 ## Context + Verification Budget
 
 - **Trivial**: no docs.

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.2.2 features.
+This folder stores shared UKit runtime state for v1.3.0 features.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.2",
+  "version": "1.3.0",
   "agent": "claude-code",
   "compact": {
     "enabled": true,
@@ -86,6 +86,17 @@
     "maxRetries": 1,
     "confidenceThreshold": 50
   },
+  "safePatch": {
+    "enabled": true,
+    "strictSharedRisk": true,
+    "largeFileLineThreshold": 800,
+    "largeFileByteThreshold": 200000,
+    "backupEnabled": true,
+    "backupRetentionDays": 30,
+    "deltaMaxChangedLines": 120,
+    "deltaMaxHunks": 3,
+    "deltaMaxDiffCells": 2000000
+  },
   "subagents": {
     "enabled": true,
     "smallTaskModel": "unic-lite",
@@ -273,6 +284,17 @@
         "decisions": "Nhóm quyết định sidecar được phép hỗ trợ.",
         "stepBudgets": "Gợi ý số bước planning tối đa theo độ lớn task trước khi reassess."
       }
+    },
+    "safePatch": {
+      "enabled": "Bật Safe Patch Protocol: UKit âm thầm chặn patch stale/ambiguous trên file rủi ro và giữ an toàn encoding khi helper nội bộ sửa file.",
+      "strictSharedRisk": "Nếu true, file runtime/shared-risk như .claude/hooks hoặc .claude/ukit sẽ bị guard chặt hơn; người dùng vẫn không cần nhớ command mới.",
+      "largeFileLineThreshold": "Số dòng từ đó file được xem là lớn và cần anchor/spec guard kỹ hơn.",
+      "largeFileByteThreshold": "Kích thước byte từ đó file được xem là lớn/rủi ro khi agent edit.",
+      "backupEnabled": "Nếu true, UKit tạo rollback bytes dưới .ukit/storage/backups cho edit rủi ro.",
+      "backupRetentionDays": "Số ngày giữ backup rollback cũ trong .ukit/storage/backups; UKit chỉ tự xoá folder backup có tên ngày hợp lệ YYYY-MM-DD.",
+      "deltaMaxChangedLines": "Ngân sách dòng đổi mặc định cho kiểm tra delta sau này.",
+      "deltaMaxHunks": "Ngân sách hunk đổi mặc định cho kiểm tra delta sau này.",
+      "deltaMaxDiffCells": "Giới hạn cell LCS khi tính delta; quá ngưỡng này UKit dùng fallback tuyến tính để tránh chậm trên file rất lớn."
     }
   }
 }