claudekit-cli 4.3.1 → 4.4.0-dev.2

package/README.md

@@ -50,7 +50,7 @@ Without a purchased kit and repository access, the CLI will not be able to downl
 
 The ClaudeKit CLI is published on npm at [npmjs.com/package/claudekit-cli](https://www.npmjs.com/package/claudekit-cli).
 
-End-user runtime note: global installs from `npm`, `pnpm`, `yarn`, or `bun` all execute the packaged Node.js CLI. Bun is optional for users and only needed for local ClaudeKit CLI development workflows.
+End-user runtime note: global installs from `npm`, `pnpm`, `yarn`, or `bun` all execute the packaged Node.js CLI. Bun is optional for users and only needed for local ClaudeKit CLI development workflows. Most commands do not require native build tools; `ck content` uses an optional SQLite driver and shows remediation steps if that driver is unavailable.
 
 ### Using npm (Recommended)
 
@@ -407,6 +407,8 @@ ck content start --verbose
 
 **Features:** 11-phase pipeline (scan → filter → classify → context → create → validate → review → photo → publish → engage → analyze), noise filtering, context caching (24h TTL), content validation, photo generation, 3 review modes (auto/manual/hybrid), quiet hours scheduling, engagement tracking, SQLite database, platform-specific adapters.
 
+**Runtime dependency:** `ck content` uses the optional native SQLite driver `better-sqlite3`. If the driver is unavailable, other CLI commands still work and `ck content` prints reinstall/build-tool guidance.
+
 **Config:** `.ck.json` under `content` key. See [docs/ck-content.md](./docs/ck-content.md) for full configuration reference.
 
 ### Other Commands

package/bin/postinstall-hook-restore.cjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const MAX_SETTINGS_BYTES = 5 * 1024 * 1024;
+const SAFE_KIT_NAMES = new Set(["engineer", "marketing"]);
+const COMPLETE_HOOK_SENTINELS = new Set(["session-init", "session-state", "subagent-init"]);
+const LEGACY_SPARSE_HOOK_SENTINELS = new Set([
+	"descriptive-name",
+	"privacy-block",
+	"scout-block",
+	"simplify-gate",
+]);
+
+function getHomeDir() {
+	return process.env.CK_TEST_HOME || os.homedir();
+}
+
+function readJsonFile(filePath) {
+	try {
+		if (!filePath || !fs.existsSync(filePath)) return null;
+		const stat = fs.statSync(filePath);
+		if (!stat.isFile() || stat.size > MAX_SETTINGS_BYTES) return null;
+		return JSON.parse(fs.readFileSync(filePath, "utf8").replace(/^\uFEFF/, ""));
+	} catch {
+		return null;
+	}
+}
+
+function normalizeCommand(command) {
+	if (!command) return "";
+	let normalized = String(command).replace(/"/g, "");
+	normalized = normalized.replace(/~\//g, "$HOME/");
+	normalized = normalized.replace(/\$\{HOME\}/g, "$HOME");
+	normalized = normalized.replace(/\$CLAUDE_PROJECT_DIR/g, "$HOME");
+	normalized = normalized.replace(/%USERPROFILE%/g, "$HOME");
+	normalized = normalized.replace(/%CLAUDE_PROJECT_DIR%/g, "$HOME");
+	normalized = normalized.replace(/(^|\s)(?:\.\/)?\.claude\//g, "$1$HOME/.claude/");
+	normalized = normalized.replace(/\\/g, "/");
+	return normalized.replace(/\s+/g, " ").trim();
+}
+
+function collectHookCommands(settings) {
+	const commands = new Set();
+	for (const entries of Object.values(settings?.hooks || {})) {
+		if (!Array.isArray(entries)) continue;
+		for (const entry of entries) {
+			if (typeof entry?.command === "string") commands.add(normalizeCommand(entry.command));
+			if (!Array.isArray(entry?.hooks)) continue;
+			for (const hook of entry.hooks) {
+				if (typeof hook?.command === "string") commands.add(normalizeCommand(hook.command));
+			}
+		}
+	}
+	return commands;
+}
+
+function extractCkHookName(command) {
+	if (!String(command || "").trim().startsWith("node ")) return null;
+	const normalized = String(command).replace(/\\/g, "/");
+	const match = normalized.match(/\/hooks\/([^/"'\s]+)\.(?:cjs|mjs|js)(?:["'\s]|$)/);
+	return match?.[1] || null;
+}
+
+function installedHookCommands(config) {
+	return Object.values(config?.kits || {}).flatMap((entry) =>
+		Array.isArray(entry?.installedSettings?.hooks) ? entry.installedSettings.hooks : [],
+	);
+}
+
+function hasInstalledKit(config) {
+	return Object.keys(config?.kits || {}).some((kitName) => normalizeKitName(kitName));
+}
+
+function hasLegacySparseCkHooks(settings, config) {
+	if (!hasInstalledKit(config)) return false;
+
+	const hookNames = new Set();
+	for (const command of collectHookCommands(settings)) {
+		const hookName = extractCkHookName(command);
+		if (hookName) hookNames.add(hookName);
+	}
+
+	const hasKnownSparseHook = [...LEGACY_SPARSE_HOOK_SENTINELS].some((hookName) =>
+		hookNames.has(hookName),
+	);
+	if (!hasKnownSparseHook) return false;
+
+	const disabledHooks = new Set(
+		Object.entries(config?.hooks || {})
+			.filter(([, enabled]) => enabled === false)
+			.map(([name]) => name),
+	);
+
+	return [...COMPLETE_HOOK_SENTINELS].some(
+		(hookName) => !disabledHooks.has(hookName) && !hookNames.has(hookName),
+	);
+}
+
+function countMissingCkHookRegistrations(claudeDir) {
+	const settings = readJsonFile(path.join(claudeDir, "settings.json"));
+	const config = readJsonFile(path.join(claudeDir, ".ck.json"));
+	if (!settings || !config) return 0;
+
+	const existingCommands = collectHookCommands(settings);
+	const disabledHooks = new Set(
+		Object.entries(config.hooks || {})
+			.filter(([, enabled]) => enabled === false)
+			.map(([name]) => name),
+	);
+
+	let missing = 0;
+	for (const command of installedHookCommands(config)) {
+		const hookName = extractCkHookName(command);
+		if (hookName && disabledHooks.has(hookName)) continue;
+		if (!existingCommands.has(normalizeCommand(command))) missing++;
+	}
+
+	if (missing === 0 && installedHookCommands(config).length === 0) {
+		return hasLegacySparseCkHooks(settings, config) ? 1 : 0;
+	}
+
+	return missing;
+}
+
+function normalizeKitName(name) {
+	const normalized = String(name || "").toLowerCase();
+	if (normalized.includes("engineer")) return "engineer";
+	if (normalized.includes("marketing")) return "marketing";
+	return SAFE_KIT_NAMES.has(normalized) ? normalized : null;
+}
+
+function getInstalledKit(claudeDir) {
+	const metadata = readJsonFile(path.join(claudeDir, "metadata.json"));
+	const metadataKit = normalizeKitName(Object.keys(metadata?.kits || {})[0] || metadata?.name);
+	if (metadataKit) {
+		const kitVersion = metadata?.kits?.[metadataKit]?.version || metadata?.version || "";
+		return { kit: metadataKit, isBeta: String(kitVersion).includes("beta") };
+	}
+
+	const config = readJsonFile(path.join(claudeDir, ".ck.json"));
+	const configKit = normalizeKitName(Object.keys(config?.kits || {})[0]);
+	return configKit ? { kit: configKit, isBeta: false } : null;
+}
+
+function collectCandidateClaudeDirs(settingsFiles) {
+	const dirs = new Set();
+	for (const settingsFile of settingsFiles) dirs.add(path.dirname(settingsFile));
+	return [...dirs];
+}
+
+function resolveCkEntrypoint() {
+	return process.env.CK_POSTINSTALL_CK_BIN || path.join(__dirname, "ck.js");
+}
+
+function restoreMissingHookRegistrations(settingsFiles) {
+	if (process.env.CK_POSTINSTALL_SKIP_RESTORE_CK_HOOKS === "1") return 0;
+
+	let restored = 0;
+	for (const claudeDir of collectCandidateClaudeDirs(settingsFiles)) {
+		const missing = countMissingCkHookRegistrations(claudeDir);
+		if (missing <= 0) continue;
+
+		const installedKit = getInstalledKit(claudeDir);
+		if (!installedKit?.kit) continue;
+
+		const homeDir = getHomeDir();
+		const globalClaudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, ".claude");
+		const isGlobal = path.resolve(claudeDir) === path.resolve(globalClaudeDir);
+		const args = [resolveCkEntrypoint(), "init"];
+		if (isGlobal) args.push("-g");
+		args.push("--kit", installedKit.kit, "--yes", "--restore-ck-hooks", "--install-skills");
+		if (installedKit.isBeta) args.push("--beta");
+
+		const result = spawnSync(process.execPath, args, {
+			env: { ...process.env, CK_POSTINSTALL_SKIP_RESTORE_CK_HOOKS: "1" },
+			stdio: process.env.CK_POSTINSTALL_DEBUG === "1" ? "inherit" : "ignore",
+		});
+		if (result.status === 0) restored += missing;
+	}
+
+	return restored;
+}
+
+module.exports = {
+	countMissingCkHookRegistrations,
+	restoreMissingHookRegistrations,
+};

package/bin/postinstall-self-heal.cjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const {
+	countMissingCkHookRegistrations,
+	restoreMissingHookRegistrations,
+} = require("./postinstall-hook-restore.cjs");
+
+const MAX_SETTINGS_BYTES = 5 * 1024 * 1024;
+
+function isLegacyDescriptiveNamePrompt(entry) {
+	if (!entry || entry.type !== "prompt" || typeof entry.prompt !== "string") return false;
+
+	const prompt = entry.prompt;
+	const lowerPrompt = prompt.toLowerCase();
+	const isOriginalLegacyPrompt =
+		prompt.includes("Use kebab-case file naming") &&
+		prompt.includes("self-documenting") &&
+		prompt.includes("Grep, Glob, Search");
+	const isDescriptiveNameKebabPrompt =
+		lowerPrompt.includes("descriptive-name") &&
+		lowerPrompt.includes("kebab-case") &&
+		(lowerPrompt.includes("file") || lowerPrompt.includes("filename"));
+
+	return isOriginalLegacyPrompt || isDescriptiveNameKebabPrompt;
+}
+
+function pruneHooks(settings) {
+	if (!settings || typeof settings !== "object" || !settings.hooks) return 0;
+
+	let pruned = 0;
+	for (const [eventName, entries] of Object.entries(settings.hooks)) {
+		if (!Array.isArray(entries)) continue;
+
+		const keptEntries = [];
+		for (const entry of entries) {
+			if (isLegacyDescriptiveNamePrompt(entry)) {
+				pruned++;
+				continue;
+			}
+
+			if (Array.isArray(entry?.hooks)) {
+				const keptHooks = entry.hooks.filter((hook) => {
+					if (isLegacyDescriptiveNamePrompt(hook)) {
+						pruned++;
+						return false;
+					}
+					return true;
+				});
+				if (keptHooks.length > 0) keptEntries.push({ ...entry, hooks: keptHooks });
+				continue;
+			}
+
+			keptEntries.push(entry);
+		}
+
+		if (keptEntries.length === 0) {
+			delete settings.hooks[eventName];
+		} else {
+			settings.hooks[eventName] = keptEntries;
+		}
+	}
+
+	if (Object.keys(settings.hooks).length === 0) settings.hooks = undefined;
+	return pruned;
+}
+
+function pruneSettingsFile(filePath) {
+	try {
+		if (!filePath || !fs.existsSync(filePath)) return 0;
+		const stat = fs.statSync(filePath);
+		if (!stat.isFile() || stat.size > MAX_SETTINGS_BYTES) return 0;
+
+		const settings = JSON.parse(fs.readFileSync(filePath, "utf8"));
+		const pruned = pruneHooks(settings);
+		if (pruned > 0) {
+			fs.writeFileSync(filePath, `${JSON.stringify(settings, null, 2)}\n`);
+		}
+		return pruned;
+	} catch {
+		return 0;
+	}
+}
+
+function getHomeDir() {
+	return process.env.CK_TEST_HOME || os.homedir();
+}
+
+function addIfSettingsFile(files, filePath) {
+	if (!filePath) return;
+	const base = path.basename(filePath);
+	if (
+		base === "settings.json" ||
+		base === "settings.local.json" ||
+		base.endsWith(".settings.json")
+	) {
+		files.add(path.resolve(filePath));
+	}
+}
+
+function collectCandidateSettingsFiles() {
+	const files = new Set();
+	const initCwd = process.env.INIT_CWD;
+	if (initCwd && path.isAbsolute(initCwd)) {
+		addIfSettingsFile(files, path.join(initCwd, ".claude", "settings.json"));
+		addIfSettingsFile(files, path.join(initCwd, ".claude", "settings.local.json"));
+	}
+
+	const homeDir = getHomeDir();
+	const globalClaudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, ".claude");
+	addIfSettingsFile(files, path.join(globalClaudeDir, "settings.json"));
+	addIfSettingsFile(files, path.join(globalClaudeDir, "settings.local.json"));
+
+	const ccsDir = process.env.CK_TEST_CCS_DIR || path.join(homeDir, ".ccs");
+	try {
+		for (const dirent of fs.readdirSync(ccsDir, { withFileTypes: true })) {
+			if (dirent.isFile()) addIfSettingsFile(files, path.join(ccsDir, dirent.name));
+		}
+	} catch {
+		// Optional compatibility directory; skip when absent or unreadable.
+	}
+
+	return [...files];
+}
+
+function main() {
+	let pruned = 0;
+	const settingsFiles = collectCandidateSettingsFiles();
+	for (const filePath of settingsFiles) {
+		pruned += pruneSettingsFile(filePath);
+	}
+
+	const restored = restoreMissingHookRegistrations(settingsFiles);
+
+	if (pruned > 0 && process.env.CK_POSTINSTALL_DEBUG === "1") {
+		console.warn(`[claudekit-cli] Pruned ${pruned} legacy hook prompt(s)`);
+	}
+	if (restored > 0 && process.env.CK_POSTINSTALL_DEBUG === "1") {
+		console.warn(`[claudekit-cli] Restored ${restored} missing hook registration(s)`);
+	}
+}
+
+main();
+
+module.exports = {
+	collectCandidateSettingsFiles,
+	countMissingCkHookRegistrations,
+	isLegacyDescriptiveNamePrompt,
+	pruneHooks,
+	pruneSettingsFile,
+	restoreMissingHookRegistrations,
+};

package/cli-manifest.json

@@ -1,6 +1,6 @@
 {
-	"version": "4.3.1",
-	"generatedAt": "2026-05-13T17:19:29.974Z",
+	"version": "4.4.0-dev.2",
+	"generatedAt": "2026-05-30T14:38:02.947Z",
 	"commands": {
 		"agents": {
 			"name": "agents",
@@ -1188,6 +1188,10 @@
 						{
 							"flags": "--force-overwrite-settings",
 							"description": "Fully replace settings.json instead of selective merge"
+						},
+						{
+							"flags": "--restore-ck-hooks",
+							"description": "Restore CK-managed hook registrations during update self-heal"
 						}
 					]
 				},
@@ -1635,6 +1639,12 @@
 								}
 							]
 						}
+					],
+					"sections": [
+						{
+							"title": "Agent Editing Reminder",
+							"content": "After creating a plan, Claude Code agents should read `plan.md` and every generated `phase-*.md` before editing. The files already exist; Write/Edit without Read can be rejected after wasting tokens."
+						}
 					]
 				},
 				{