mova-claude-import 0.1.1 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@
 
 - создаёт полный “эталонный” скелет Claude Code‑проекта;
 - импортирует существующий проект в чистую структуру;
-- добавляет слой контроля и отчёты без “магии” и без LLM.
+- добавляет слой контроля, наблюдаемости и отчёты без “магии” и без LLM.
 
 ## Что было → что стало
 
@@ -26,23 +26,40 @@
     hooks/
   .mcp.json
   mova/
+    control_v0.json
     claude_import/v0/...
     claude_control/v0/runs/...
 ```
 
 ## Быстрый старт
 
+### Recommended flow (control_v0)
+
+```
+npx mova-claude-import init --out <dir>
+npx mova-claude-import control prefill --project <dir> --out <dir>
+npx mova-claude-import control apply --project <dir> --profile <dir>/mova/control_v0.json --mode apply
+npx mova-claude-import control check --project <dir> --profile <dir>/mova/control_v0.json
+```
+
 ### У меня уже есть папка Claude Code‑проекта
 
 ```
 npx mova-claude-import --project <in> --out <out> --zip
 ```
 
-Дальше добавьте контрольный профиль и проверьте план:
+### Quick start (existing Claude folder + preset)
 
 ```
-npx mova-claude-import control prefill --project <in> --out <out>
-npx mova-claude-import control check --project <in> --profile <out>/claude_control_profile_v0.json
+npx -y mova-claude-import@<version> preset list
+npx -y mova-claude-import@<version> control apply --preset safe_observable_v0 --project . --mode overlay
+```
+
+Дальше используйте единый контрольный файл и выполните rebuild/import:
+
+```
+<out>/mova/control_v0.json
+npx mova-claude-import --project <in> --out <out> --zip
 ```
 
 ### Я хочу создать эталонный профиль с нуля (init)
@@ -51,6 +68,18 @@ npx mova-claude-import control check --project <in> --profile <out>/claude_contr
 npx mova-claude-import init --out <dir> --zip
 ```
 
+Заполните единый контрольный файл:
+
+```
+<dir>/mova/control_v0.json
+```
+
+Затем выполните rebuild/import:
+
+```
+npx mova-claude-import --project <dir> --out <out> --zip
+```
+
 ### Контроль (preview по умолчанию)
 
 ```
@@ -69,17 +98,52 @@ npm run demo
 Руководство: `docs/CONTROL_PROFILE_GUIDE_v0.md`.
 Примеры: `examples/control_profile_min.json`, `examples/control_profile_standard.json`, `examples/control_profile_strict.json`.
 
+Единый контрольный файл для rebuild/import: `mova/control_v0.json`.
+Schema: `schemas/mova.control_v0.schema.json`.
+
 Канон схем control‑слоя: `schemas/claude_control/v0/{ds,env,global}`.
 
 ## Где смотреть отчёты/доказательства
 
 - `mova/claude_import/v0/*` — отчёты импорта и контроля качества
 - `mova/claude_control/v0/runs/*` — планы/отчёты control‑команд
+- `.mova/episodes/index.jsonl` — индекс наблюдаемости
+- `.mova/episodes/<run_id>/summary.json` — краткая сводка последнего прогона
+
+## Наблюдаемость (Observability Writer)
+
+Writer включается из `mova/control_v0.json` и через hooks пишет эпизоды:
+
+- события в `.mova/episodes/<run_id>/events.jsonl`
+- сводка в `.mova/episodes/<run_id>/summary.json`
+- индекс прогонов в `.mova/episodes/index.jsonl`
+
+Отключить можно через `observability.enable=false` в `mova/control_v0.json`.
+
+Минимальные команды:
+
+```
+npx mova-claude-import observe list --project <dir>
+npx mova-claude-import observe tail --project <dir> --run <id>
+npx mova-claude-import observe summary --project <dir> --run <id>
+```
 
 ## Для автоматизации
 
 Подробности по `--strict`, кодам завершения и CI‑проверкам — в `docs/OPERATOR_GUIDE_v0.md`.
 
+## Preset: safe_observable_v0
+
+Что делает:
+- включает observability writer и hooks
+- добавляет guardrails на опасные команды и изменения в `main`
+- добавляет start/finish команды и базовые skills
+- включает skill-eval hook и правила
+
+Что не делает:
+- не включает MCP (по умолчанию пусто)
+- не трогает секреты или локальные креды
+
 ## Ссылки
 
 - `docs/COMPATIBILITY_MATRIX.md`

package/control_surface_exclusions_v0.json

@@ -0,0 +1,8 @@
+{
+  "exclusions": [
+    {
+      "pattern": ".claude/skills/README.md",
+      "reason": "quality_v0 disallows files directly under .claude/skills"
+    }
+  ]
+}

package/dist/anthropic_profile_v0.d.ts

@@ -1,2 +1,2 @@
-export declare const anthropicProfileV0RequiredFiles: readonly ["CLAUDE.md", "MOVA.md", ".claude/settings.json", ".claude/commands/mova_context.md", ".claude/commands/mova_lint.md", ".claude/skills/mova-layer-v0/SKILL.md"];
+export declare const anthropicProfileV0RequiredFiles: readonly ["CLAUDE.md", "MOVA.md", ".claude/settings.json", ".claude/commands/mova_context.md", ".claude/commands/mova_lint.md", ".claude/skills/mova-layer-v0/SKILL.md", "mova/control_v0.json"];
 export declare function getAnthropicProfileV0Files(): Record<string, string>;

package/dist/anthropic_profile_v0.js

@@ -6,6 +6,7 @@ export const anthropicProfileV0RequiredFiles = [
     ".claude/commands/mova_context.md",
     ".claude/commands/mova_lint.md",
     ".claude/skills/mova-layer-v0/SKILL.md",
+    "mova/control_v0.json",
 ];
 export function getAnthropicProfileV0Files() {
     return {

package/dist/cli.js

@@ -3,6 +3,8 @@ import { initProfileV0 } from "./init_v0.js";
 import { controlPrefillV0 } from "./control_prefill_v0.js";
 import { controlCheckV0 } from "./control_check_v0.js";
 import { controlApplyV0 } from "./control_apply_v0.js";
+import { listObservabilityRuns, readObservabilitySummary, tailObservabilityEvents } from "./observe_v0.js";
+import { listPresets, readPresetControlRaw, resolvePreset } from "./presets_v0.js";
 function getArg(name) {
     const idx = process.argv.indexOf(name);
     if (idx === -1)
@@ -18,10 +20,15 @@ function usage(exitCode = 0) {
         "",
         "Usage:",
         "  mova-claude-import --project <dir> [--out <dir>] [--dry-run] [--strict] [--include-local] [--include-user-settings] [--no-emit-profile] [--no-emit-overlay] [--zip] [--zip-name <name>]",
-        "  mova-claude-import init --out <dir> [--zip]",
+        "  mova-claude-import init --out <dir> [--zip] [--preset <name>]",
         "  mova-claude-import control prefill --project <dir> --out <dir> [--include-local]",
         "  mova-claude-import control check --project <dir> --profile <file>",
-        "  mova-claude-import control apply --project <dir> --profile <file> [--mode preview|apply]",
+        "  mova-claude-import control apply --project <dir> --profile <file> [--mode preview|apply|overlay] [--preset <name>]",
+        "  mova-claude-import preset list",
+        "  mova-claude-import preset show <name>",
+        "  mova-claude-import observe list --project <dir>",
+        "  mova-claude-import observe tail --project <dir> --run <id> [--limit <n>]",
+        "  mova-claude-import observe summary --project <dir> --run <id>",
         "",
         "Notes:",
         "  - CLAUDE.local.md and *.local.* are excluded unless --include-local",
@@ -30,6 +37,7 @@ function usage(exitCode = 0) {
         "  - overlay emission is enabled by default; use --no-emit-overlay to skip",
         "  - zip export is disabled by default; use --zip to enable",
         "  - init creates a clean Anthropic profile v0 scaffold",
+        "  - init --preset uses preset control_v0.json + assets",
         "  - control commands run in preview by default",
     ].join("\n"));
     process.exit(exitCode);
@@ -48,15 +56,42 @@ if (subcommand === "init") {
         process.exit(2);
     }
     const emitZip = hasFlag("--zip");
-    initProfileV0(out, emitZip)
-        .then((res) => {
-        process.stdout.write(JSON.stringify(res, null, 2) + "\n");
-        process.exit(0);
-    })
-        .catch((err) => {
-        console.error(err);
-        process.exit(1);
-    });
+    const presetName = getArg("--preset");
+    if (presetName) {
+        resolvePreset(presetName)
+            .then(async (preset) => {
+            if (!preset) {
+                console.error(`Preset not found: ${presetName}`);
+                process.exit(2);
+            }
+            const raw = await readPresetControlRaw(presetName);
+            const control = raw ? JSON.parse(raw) : null;
+            if (!control) {
+                console.error(`Preset control missing: ${presetName}`);
+                process.exit(2);
+            }
+            return initProfileV0(out, emitZip, { controlOverride: control, assetsRoot: preset.assets_root });
+        })
+            .then((res) => {
+            process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+            process.exit(0);
+        })
+            .catch((err) => {
+            console.error(err);
+            process.exit(1);
+        });
+    }
+    else {
+        initProfileV0(out, emitZip)
+            .then((res) => {
+            process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+            process.exit(0);
+        })
+            .catch((err) => {
+            console.error(err);
+            process.exit(1);
+        });
+    }
 }
 else if (subcommand === "control") {
     const action = process.argv[3];
@@ -95,10 +130,13 @@ else if (subcommand === "control") {
         controlCheckV0(project, profile, out)
             .then((res) => {
             console.log([
-                "control check: ok",
+                res.exit_code && res.exit_code !== 0 ? "control check: issues" : "control check: ok",
                 `plan: ${res.plan_path}`,
                 `summary: ${res.summary_path}`,
-            ].join("\n"));
+                res.exit_code ? `exit_code: ${res.exit_code}` : null,
+            ].filter(Boolean).join("\n"));
+            if (typeof res.exit_code === "number")
+                process.exit(res.exit_code);
             process.exit(0);
         })
             .catch((err) => {
@@ -107,19 +145,164 @@ else if (subcommand === "control") {
         });
     }
     else if (action === "apply") {
-        const profile = getArg("--profile");
-        if (!profile) {
+        const out = getArg("--out") || project;
+        const mode = getArg("--mode");
+        const presetName = getArg("--preset");
+        if (presetName) {
+            resolvePreset(presetName)
+                .then(async (preset) => {
+                if (!preset) {
+                    console.error(`Preset not found: ${presetName}`);
+                    process.exit(2);
+                }
+                return controlApplyV0(project, preset.control_path, out, mode, {
+                    assetSourceRoot: preset.assets_root,
+                });
+            })
+                .then((res) => {
+                console.log([
+                    res.exit_code && res.exit_code !== 0 ? "control apply: issues" : "control apply: ok",
+                    `report: ${res.report_path}`,
+                    res.exit_code ? `exit_code: ${res.exit_code}` : null,
+                ].filter(Boolean).join("\n"));
+                if (typeof res.exit_code === "number")
+                    process.exit(res.exit_code);
+                process.exit(0);
+            })
+                .catch((err) => {
+                console.error(err);
+                process.exit(1);
+            });
+        }
+        else {
+            const profile = getArg("--profile");
+            if (!profile) {
+                usage(2);
+                process.exit(2);
+            }
+            controlApplyV0(project, profile, out, mode)
+                .then((res) => {
+                console.log([
+                    res.exit_code && res.exit_code !== 0 ? "control apply: issues" : "control apply: ok",
+                    `report: ${res.report_path}`,
+                    res.exit_code ? `exit_code: ${res.exit_code}` : null,
+                ].filter(Boolean).join("\n"));
+                if (typeof res.exit_code === "number")
+                    process.exit(res.exit_code);
+                process.exit(0);
+            })
+                .catch((err) => {
+                console.error(err);
+                process.exit(1);
+            });
+        }
+    }
+    else {
+        usage(2);
+        process.exit(2);
+    }
+}
+else if (subcommand === "preset") {
+    const action = process.argv[3];
+    if (action === "list") {
+        listPresets()
+            .then((presets) => {
+            for (const name of presets) {
+                console.log(name);
+            }
+            process.exit(0);
+        })
+            .catch((err) => {
+            console.error(err);
+            process.exit(1);
+        });
+    }
+    else if (action === "show") {
+        const name = process.argv[4];
+        if (!name) {
             usage(2);
             process.exit(2);
         }
-        const out = getArg("--out") || project;
-        const mode = getArg("--mode");
-        controlApplyV0(project, profile, out, mode)
-            .then((res) => {
-            console.log([
-                "control apply: ok",
-                `report: ${res.report_path}`,
-            ].join("\n"));
+        readPresetControlRaw(name)
+            .then((raw) => {
+            if (!raw) {
+                console.error(`Preset not found: ${name}`);
+                process.exit(2);
+            }
+            process.stdout.write(raw + "\n");
+            process.exit(0);
+        })
+            .catch((err) => {
+            console.error(err);
+            process.exit(1);
+        });
+    }
+    else {
+        usage(2);
+        process.exit(2);
+    }
+}
+else if (subcommand === "observe") {
+    const action = process.argv[3];
+    const project = getArg("--project");
+    if (!project) {
+        usage(2);
+        process.exit(2);
+    }
+    if (action === "list") {
+        listObservabilityRuns(project)
+            .then((runs) => {
+            if (!runs.length) {
+                console.log("observe list: no runs");
+                process.exit(0);
+            }
+            for (const run of runs) {
+                console.log(JSON.stringify(run));
+            }
+            process.exit(0);
+        })
+            .catch((err) => {
+            console.error(err);
+            process.exit(1);
+        });
+    }
+    else if (action === "tail") {
+        const runId = getArg("--run");
+        if (!runId) {
+            usage(2);
+            process.exit(2);
+        }
+        const limitRaw = getArg("--limit");
+        const limit = limitRaw ? Number(limitRaw) : 20;
+        tailObservabilityEvents(project, runId, Number.isFinite(limit) ? limit : 20)
+            .then((lines) => {
+            if (!lines.length) {
+                console.log("observe tail: no events");
+                process.exit(0);
+            }
+            for (const line of lines) {
+                console.log(line);
+            }
+            process.exit(0);
+        })
+            .catch((err) => {
+            console.error(err);
+            process.exit(1);
+        });
+    }
+    else if (action === "summary") {
+        const runId = getArg("--run");
+        if (!runId) {
+            usage(2);
+            process.exit(2);
+        }
+        readObservabilitySummary(project, runId)
+            .then((summary) => {
+            if (!summary) {
+                console.log("observe summary: not found");
+                process.exit(0);
+            }
+            process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
             process.exit(0);
         })
             .catch((err) => {

package/dist/control_apply_v0.d.ts

@@ -1,6 +1,10 @@
 type ApplyResult = {
     run_id: string;
     report_path: string;
+    exit_code?: number;
 };
-export declare function controlApplyV0(projectDir: string, profilePath: string, outDir: string, mode?: string): Promise<ApplyResult>;
+type ApplyOptions = {
+    assetSourceRoot?: string;
+};
+export declare function controlApplyV0(projectDir: string, profilePath: string, outDir: string, mode?: string, options?: ApplyOptions): Promise<ApplyResult>;
 export {};

package/dist/control_apply_v0.js

@@ -4,6 +4,9 @@ import { stableStringify } from "./stable_json.js";
 import { stableSha256 } from "./redaction.js";
 import { buildMovaControlEntryV0, MOVA_CONTROL_ENTRY_MARKER } from "./mova_overlay_v0.js";
 import { ensureClaudeControlSurfacesV0 } from "./claude_profile_scaffold_v0.js";
+import { controlToMcpJson, controlToSettingsV0, normalizeControlV0 } from "./control_v0.js";
+import { validateControlV0Schema } from "./control_v0_schema.js";
+import { getMovaObserveScriptV0 } from "./observability_writer_v0.js";
 async function exists(p) {
     try {
         await fs.stat(p);
@@ -24,6 +27,37 @@ async function writeJson(p, obj) {
 function computeRunId(parts) {
     return stableSha256(parts.join("|")).slice(0, 16);
 }
+function mergeOverlayValue(existing, incoming) {
+    if (existing === undefined)
+        return incoming;
+    const existingArr = Array.isArray(existing) ? existing : null;
+    const incomingArr = Array.isArray(incoming) ? incoming : null;
+    if (existingArr || incomingArr) {
+        const left = existingArr ?? (existing === undefined ? [] : [existing]);
+        const right = incomingArr ?? (incoming === undefined ? [] : [incoming]);
+        const seen = new Set(left.map((item) => stableStringify(item)));
+        const merged = left.slice();
+        for (const item of right) {
+            const key = stableStringify(item);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push(item);
+        }
+        return merged;
+    }
+    if (existing && typeof existing === "object" && incoming && typeof incoming === "object") {
+        const out = { ...existing };
+        for (const [key, value] of Object.entries(incoming)) {
+            out[key] = mergeOverlayValue(out[key], value);
+        }
+        return out;
+    }
+    return existing;
+}
+function mergeSettingsOverlay(existing, incoming) {
+    return mergeOverlayValue(existing ?? {}, incoming ?? {});
+}
 function updateClaude(content, marker, block) {
     if (content.includes(marker)) {
         const idx = content.indexOf(marker);
@@ -34,15 +68,38 @@ function updateClaude(content, marker, block) {
     }
     return `${block}\n${content}`;
 }
-export async function controlApplyV0(projectDir, profilePath, outDir, mode) {
+export async function controlApplyV0(projectDir, profilePath, outDir, mode, options) {
     await ensureClaudeControlSurfacesV0(projectDir);
     const profile = await readJson(profilePath);
-    const applyMode = mode ?? profile?.apply?.default_apply_mode ?? "preview";
+    const isControlV0 = profile?.version === "control_v0";
+    const control = isControlV0 ? normalizeControlV0(profile).control : null;
+    if (isControlV0) {
+        const validation = await validateControlV0Schema(profile);
+        if (!validation.ok) {
+            const runId = computeRunId([profilePath, "invalid_schema"]);
+            const runBase = path.join(outDir, "mova", "claude_control", "v0", "runs", runId);
+            const reportPath = path.join(runBase, "control_apply_report_v0.json");
+            const report = {
+                profile_version: "v0",
+                run_id: runId,
+                project_dir: projectDir,
+                profile_path: profilePath,
+                mode: mode ?? "preview",
+                outcome_code: "INVALID_SCHEMA",
+                errors: validation.errors ?? [],
+            };
+            await writeJson(reportPath, report);
+            return { run_id: runId, report_path: reportPath, exit_code: 2 };
+        }
+    }
+    const applyMode = mode ?? (isControlV0 && control?.policy?.mode === "report_only" ? "preview" : profile?.apply?.default_apply_mode) ?? "preview";
+    const isOverlay = applyMode === "overlay";
+    const assetSourceRoot = options?.assetSourceRoot ?? projectDir;
     const claudePath = path.join(projectDir, "CLAUDE.md");
     const mcpPath = path.join(projectDir, ".mcp.json");
     const claudeExists = await exists(claudePath);
     const mcpExists = await exists(mcpPath);
-    const marker = profile?.anthropic?.claude_md?.marker ?? MOVA_CONTROL_ENTRY_MARKER;
+    const marker = control?.claude_md?.marker ?? profile?.anthropic?.claude_md?.marker ?? MOVA_CONTROL_ENTRY_MARKER;
     const runId = computeRunId([profilePath, claudeExists ? "claude" : "", mcpExists ? "mcp" : "", marker, applyMode]);
     const runBase = path.join(outDir, "mova", "claude_control", "v0", "runs", runId);
     const overlayParams = {
@@ -56,15 +113,75 @@ export async function controlApplyV0(projectDir, profilePath, outDir, mode) {
         exportManifestFile: "export_manifest_v0.json",
     };
     const controlEntry = buildMovaControlEntryV0(overlayParams);
-    const applied = { claude_md: false, mcp_json: false, settings: false };
-    if (applyMode === "apply") {
-        if (profile?.anthropic?.claude_md?.inject_control_entry && claudeExists) {
+    const applied = { claude_md: false, mcp_json: false, settings: false, assets: false, lsp: false };
+    if (applyMode === "apply" || applyMode === "overlay") {
+        if ((control?.claude_md?.inject_control_entry ?? profile?.anthropic?.claude_md?.inject_control_entry) && claudeExists) {
             const raw = await fs.readFile(claudePath, "utf8");
             const updated = updateClaude(raw, marker, controlEntry);
             await fs.writeFile(claudePath, updated, "utf8");
             applied.claude_md = true;
         }
-        if (profile?.anthropic?.mcp?.servers && mcpExists) {
+        if (control) {
+            const settingsPath = path.join(projectDir, ".claude", "settings.json");
+            const settingsGenerated = controlToSettingsV0(control);
+            if (isOverlay && (await exists(settingsPath))) {
+                const current = await readJson(settingsPath);
+                const merged = mergeSettingsOverlay(current, settingsGenerated);
+                await writeJson(settingsPath, merged);
+            }
+            else {
+                await writeJson(settingsPath, settingsGenerated);
+            }
+            applied.settings = true;
+            if (!(isOverlay && (await exists(mcpPath)))) {
+                await writeJson(path.join(projectDir, ".mcp.json"), controlToMcpJson(control));
+                applied.mcp_json = true;
+            }
+            const assets = [
+                ...control.assets.skills,
+                ...control.assets.agents,
+                ...control.assets.commands,
+                ...control.assets.rules,
+                ...control.assets.hooks,
+                ...control.assets.workflows,
+                ...control.assets.docs,
+                ...control.assets.dotfiles,
+                ...control.assets.schemas,
+            ];
+            for (const asset of assets) {
+                const target = path.join(projectDir, asset.path);
+                if (isOverlay && (await exists(target)))
+                    continue;
+                const sourceRel = asset.source_path ?? asset.path;
+                const source = path.isAbsolute(sourceRel) ? sourceRel : path.join(assetSourceRoot, sourceRel);
+                try {
+                    await fs.stat(source);
+                }
+                catch {
+                    continue;
+                }
+                await fs.mkdir(path.dirname(target), { recursive: true });
+                if (source !== target) {
+                    await fs.copyFile(source, target);
+                }
+            }
+            applied.assets = assets.length > 0;
+            if (control.lsp.managed && Array.isArray(control.lsp.enabled_plugins)) {
+                const lspPath = path.join(projectDir, control.lsp.config_path);
+                if (!(isOverlay && (await exists(lspPath)))) {
+                    await writeJson(lspPath, { enabled_plugins: control.lsp.enabled_plugins });
+                }
+                applied.lsp = true;
+            }
+            if (control.observability.enable && control.observability.writer?.script_path) {
+                const scriptPath = path.join(projectDir, control.observability.writer.script_path);
+                if (!(isOverlay && (await exists(scriptPath)))) {
+                    await fs.mkdir(path.dirname(scriptPath), { recursive: true });
+                    await fs.writeFile(scriptPath, getMovaObserveScriptV0(), "utf8");
+                }
+            }
+        }
+        else if (profile?.anthropic?.mcp?.servers && mcpExists) {
             const mcp = await readJson(mcpPath);
             const merged = { ...mcp, servers: profile.anthropic.mcp.servers };
             await fs.writeFile(mcpPath, stableStringify(merged) + "\n", "utf8");
@@ -77,7 +194,7 @@ export async function controlApplyV0(projectDir, profilePath, outDir, mode) {
         project_dir: projectDir,
         profile_path: profilePath,
         mode: applyMode,
-        outcome_code: applyMode === "apply" ? "APPLIED" : "PREVIEW",
+        outcome_code: applyMode === "apply" || applyMode === "overlay" ? "APPLIED" : "PREVIEW",
         applied,
     };
     const reportPath = path.join(runBase, "control_apply_report_v0.json");

package/dist/control_check_v0.d.ts

@@ -2,6 +2,7 @@ type CheckResult = {
     run_id: string;
     plan_path: string;
     summary_path: string;
+    exit_code?: number;
 };
 export declare function controlCheckV0(projectDir: string, profilePath: string, outDir: string): Promise<CheckResult>;
 export {};