zigmini 0.9.0-beta.3 → 1.0.0-beta.2

package/src/cli/rules.ts

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { INSTALL_RULES_FILE, PACKAGE_RULES_FILE, ruleMapping, splitRuleItems } from "../agent-rules.ts";
+
+/**
+ * `zigmini rules` lists the package (common) rule items with their number, fixed id and first line.
+ * `zigmini rules check` shows how each item of <home>/rules.md maps onto them: it replaces one (by id), it is new, or it
+ * names an id the package no longer has (exit 1). The numbers are only a reading order, never a priority.
+ */
+export interface RulesDeps {
+	readonly home: string;
+	readonly lang: "en" | "ko";
+	readonly out: (text: string) => void;
+	readonly err: (text: string) => void;
+	readonly packageFile?: string;
+}
+
+const TEXT = {
+	en: { usage: "Usage: zigmini rules [check]", noPackage: "package rules file not found", noInstall: "no rules.md in this installation: nothing to map",
+		replaces: (id: string, target: string) => `replaces common ${target} (${id})`, fresh: "new rule (appended after the common rules)",
+		unknown: (id: string) => `unknown id ${id}: appended as a new rule; fix or remove the replaces comment` },
+	ko: { usage: "사용법: zigmini rules [check]", noPackage: "공통 규칙 파일이 없습니다", noInstall: "이 설치에 rules.md가 없습니다. 매핑할 항목이 없습니다",
+		replaces: (id: string, target: string) => `공통 ${target}번(${id})을 대체`, fresh: "신규 규칙(공통 규칙 뒤에 붙음)",
+		unknown: (id: string) => `없는 ID ${id}: 신규로 붙습니다. replaces 주석을 고치거나 지우세요` },
+} as const;
+
+function firstLine(raw: string): string {
+	const line = raw.split("\n")[0]!.replace(/<!--[\s\S]*?-->/g, "").replace(/^\d+\.\s*/, "").trim();
+	return line.length > 60 ? `${line.slice(0, 60)}…` : line;
+}
+
+function readText(path: string): string | null {
+	return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
+export function rulesCommand(argv: readonly string[], deps: RulesDeps): number {
+	const text = TEXT[deps.lang];
+	if (argv.length > 1 || (argv.length === 1 && argv[0] !== "check")) {
+		deps.err(`${text.usage}\n`);
+		return 2;
+	}
+	const pkg = readText(deps.packageFile ?? PACKAGE_RULES_FILE);
+	if (pkg === null) {
+		deps.err(`${text.noPackage}\n`);
+		return 2;
+	}
+	if (argv.length === 0) {
+		for (const item of splitRuleItems(pkg).items) deps.out(`${item.number.padStart(2)}  ${item.id ?? "------"}  ${firstLine(item.raw)}\n`);
+		return 0;
+	}
+	const install = readText(join(deps.home, INSTALL_RULES_FILE));
+	if (install === null) {
+		deps.out(`${text.noInstall}\n`);
+		return 0;
+	}
+	const mapping = ruleMapping(pkg, install);
+	for (const entry of mapping) {
+		const state = entry.state === "replaces" ? text.replaces(entry.replaces!, entry.target!) : entry.state === "new" ? text.fresh : text.unknown(entry.replaces!);
+		deps.out(`${entry.number.padStart(2)}  ${state}\n`);
+	}
+	return mapping.some((entry) => entry.state === "unknown_id") ? 1 : 0;
+}
+
+/** Ids named in rules.md that the package rules no longer have (doctor warns about them). */
+export function unknownRuleIds(home: string, packageFile: string = PACKAGE_RULES_FILE): string[] {
+	const pkg = readText(packageFile);
+	const install = readText(join(home, INSTALL_RULES_FILE));
+	if (pkg === null || install === null) return [];
+	return ruleMapping(pkg, install).filter((entry) => entry.state === "unknown_id").map((entry) => entry.replaces!);
+}

package/src/cli/scan.ts

@@ -0,0 +1,414 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { accessSync, closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { runtimePaths, securityBaselinePaths, type Env } from "../runtime/paths.ts";
+import { hashOnlySource, readBaseline, resolveBaselineSource, type BaselineFile } from "../security/baseline.ts";
+import { applyRepoAllow, loadPrivateSet, parseList, parseObjectExceptions, scanGitObjects, scanTracked, type PrivateFinding } from "../security/repo-scan.ts";
+import { findPrivate, hashTerm, HASH_SALT, machineTerms, normalizeTerm, PUBLIC_ACCOUNT, tildeHome, type PrivateSet } from "../security/terms.ts";
+import type { Language } from "./messages.ts";
+
+export type ScanExitCode = 0 | 1 | 2 | 3;
+export type ScanScope = "all" | "tracked" | "git";
+export interface ScanOptions {
+	readonly repo: string;
+	readonly scope: ScanScope;
+	readonly devRef?: string;
+	readonly gitDir?: string;
+	readonly baseline?: string;
+	readonly out?: string;
+	readonly exceptions?: string;
+	readonly json: boolean;
+	readonly quiet: boolean;
+	readonly syncHashes: boolean;
+	readonly prune: boolean;
+	readonly help: boolean;
+}
+export class ScanError extends Error {
+	constructor(readonly code: string, readonly exitCode: 2 | 3 = 2) { super(code); }
+}
+const USAGE = "zigmini scan [<repo>] [--scope all|tracked|git] [--dev-ref <ref>] [--git-dir <path>] [--baseline <file>] [--json] [--out <file>] [--sync-hashes] [--prune] [--exceptions <file>] [--quiet] [--help]";
+const TEXT = {
+	en: { usage: "Usage", invalid: "Invalid argument or combination", error: "Scan error", output: "Report output failed",
+		legacy: "Warning: using the legacy private list; import it into the security baseline." },
+	ko: { usage: "사용법", invalid: "잘못된 인자 또는 조합", error: "검사 오류", output: "보고 출력 실패",
+		legacy: "경고: 기존 비공개 목록을 사용합니다. 보안 기준으로 가져오세요." },
+} as const;
+export function scanHelp(lang: Language): string {
+	return `${TEXT[lang].usage}: ${USAGE}\n`;
+}
+
+/** Parse once. Help takes precedence even over unknown flags and missing values. */
+export function parseScanArgs(argv: readonly string[], cwd = process.cwd(), lang: Language = "en"): ScanOptions | string {
+	const defaults: ScanOptions = { repo: resolve(cwd), scope: "all", json: false, quiet: false, syncHashes: false, prune: false, help: false };
+	if (argv.includes("--help") || argv.includes("-h")) return { ...defaults, help: true };
+	const fail = (flags: string) => `${TEXT[lang].invalid}: ${flags}`;
+	const values = new Map<string, string>();
+	const switches = new Set<string>();
+	let repo: string | undefined;
+	for (let i = 0; i < argv.length; i++) {
+		const flag = argv[i] ?? "";
+		if (["--json", "--quiet", "--sync-hashes", "--prune"].includes(flag)) {
+			if (switches.has(flag)) return fail(flag);
+			switches.add(flag);
+		} else if (["--scope", "--dev-ref", "--git-dir", "--baseline", "--out", "--exceptions"].includes(flag)) {
+			if (values.has(flag)) return fail(flag);
+			const value = argv[++i];
+			if (value === undefined || value === "" || value.startsWith("-") || /[\0\r\n]/.test(value)) return fail(flag);
+			values.set(flag, value);
+		} else {
+			if (flag.startsWith("-")) return fail("unknown option");
+			if (repo !== undefined || flag === "" || /[\0\r\n]/.test(flag)) return fail("<repo>");
+			repo = resolve(cwd, flag);
+		}
+	}
+	const scope = values.get("--scope") ?? "all";
+	if (scope !== "all" && scope !== "tracked" && scope !== "git") return fail("--scope");
+	const devRef = values.get("--dev-ref");
+	if (devRef !== undefined && !["dev", "refs/heads/dev", "origin/dev", "refs/remotes/origin/dev"].includes(devRef)) return fail("--dev-ref");
+	const syncHashes = switches.has("--sync-hashes"), prune = switches.has("--prune");
+	if (syncHashes && values.has("--scope")) return fail("--sync-hashes --scope");
+	if (syncHashes && devRef !== undefined) return fail("--sync-hashes --dev-ref");
+	if (scope === "tracked" && devRef !== undefined) return fail("--scope tracked --dev-ref");
+	if (prune && !syncHashes) return fail("--prune --sync-hashes");
+	if (values.has("--exceptions") && scope === "tracked") return fail("--exceptions --scope tracked");
+	if (values.has("--exceptions") && syncHashes) return fail("--exceptions --sync-hashes");
+	const path = (flag: string) => { const value = values.get(flag); return value === undefined ? undefined : resolve(cwd, value); };
+	return { ...defaults, repo: repo ?? defaults.repo, scope, devRef, gitDir: path("--git-dir"),
+		baseline: path("--baseline"), out: path("--out"), exceptions: path("--exceptions"),
+		json: switches.has("--json"), quiet: switches.has("--quiet"), syncHashes, prune };
+}
+
+export interface ScanTarget {
+	readonly root: string;
+	/** Per-worktree metadata, not the common directory: its HEAD selects the requested branch. */
+	readonly gitDir: string;
+	readonly commonGitDir: string;
+	readonly head: string | null;
+	readonly bare: boolean;
+	readonly exceptions: ReadonlySet<string>;
+}
+
+/** Validate inputs without opening a baseline. protectedPaths contains all selectable baseline paths (todo 14). */
+export function prepareScan(options: ScanOptions, protectedPaths: readonly string[] = scanBaselinePaths(options)): ScanTarget {
+	const requested = realpathSync(options.repo);
+	const git = (args: readonly string[]) => execFileSync("git", [...args], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+	const selected = ["-C", requested];
+	const gitDir = realpathSync(git([...selected, "rev-parse", "--absolute-git-dir"]));
+	const commonGitDir = realpathSync(git([...selected, "rev-parse", "--path-format=absolute", "--git-common-dir"]));
+	const bare = git([...selected, "rev-parse", "--is-bare-repository"]) === "true";
+	if (bare && (options.scope !== "git" || options.syncHashes)) throw new ScanError("bare_requires_scope_git");
+	const root = bare ? commonGitDir : realpathSync(git([...selected, "rev-parse", "--show-toplevel"]));
+	if (options.gitDir !== undefined) {
+		const supplied = realpathSync(git(["--git-dir", options.gitDir, "rev-parse", "--path-format=absolute", "--git-common-dir"]));
+		if (supplied !== commonGitDir) throw new ScanError("git_dir_repo_mismatch");
+	}
+	// Canonical refs avoid Git's ambiguous short-name resolution; this check adds no traversal roots.
+	if (options.devRef !== undefined) {
+		const ref = options.devRef === "dev" ? "refs/heads/dev" : options.devRef === "origin/dev" ? "refs/remotes/origin/dev" : options.devRef;
+		git([...selected, "show-ref", "--verify", "--", ref]);
+	}
+	const head = options.scope === "tracked" || options.syncHashes ? null : git([...selected, "rev-parse", "--verify", "HEAD"]);
+	if (options.out !== undefined) {
+		try { lstatSync(options.out); throw new ScanError("out_exists"); }
+		catch (error) {
+			if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+		}
+		const output = join(realpathSync(dirname(options.out)), basename(options.out));
+		const protectedFiles = [...protectedPaths, ...(options.baseline === undefined ? [] : [options.baseline]),
+			join(root, "scripts/private-strings.hashes.json")];
+		for (const file of protectedFiles) {
+			let canonical = resolve(file);
+			try { canonical = join(realpathSync(dirname(file)), basename(file)); }
+			catch (error) {
+				if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+			}
+			if (output === canonical) throw new ScanError("out_protected_file");
+		}
+		if ([gitDir, commonGitDir, join(root, ".git")].some((dir) => output === dir || output.startsWith(`${dir}${sep}`))) {
+			throw new ScanError("out_git_data");
+		}
+		accessSync(dirname(output), constants.W_OK);
+	}
+	const exceptions = options.exceptions === undefined ? new Set<string>() : parseObjectExceptions(readFileSync(options.exceptions, "utf8"));
+	return { root, gitDir, commonGitDir, head, bare, exceptions };
+}
+
+export type ScanFreshness = "verified" | "unchecked_offline" | "stale" | "mismatch" | "probe_failed" | "legacy_unverifiable";
+export interface ScanBaseline { readonly source: "baseline" | "legacy-list"; readonly revision: number | null }
+export interface ResolvedScanBaseline extends ScanBaseline {
+	/** Keep the validated snapshot for revision checks and execution; never reopen the source. */
+	readonly file: BaselineFile | null;
+	readonly terms: readonly string[];
+	readonly home: string;
+	readonly user: string;
+}
+export interface ScanBaselineDeps {
+	readonly env?: Env;
+	readonly machine?: { readonly home: string; readonly user: string };
+	readonly lang?: Language;
+	readonly err: (text: string) => void;
+}
+
+/** Protect every candidate, including absent defaults, before selecting or reading a baseline. */
+export function scanBaselinePaths(options: ScanOptions, env: Env = process.env): readonly string[] {
+	const defaults = securityBaselinePaths({ ...env, ZGW_SECURITY_BASELINE_FILE: undefined, ZIGMINI_PRIVATE_STRINGS: undefined }, runtimePaths(env));
+	return [defaults.securityBaselineFile, defaults.legacyPrivateStringsFile,
+		options.baseline, env.ZGW_SECURITY_BASELINE_FILE, env.ZIGMINI_PRIVATE_STRINGS]
+		.filter((path): path is string => path !== undefined && path.trim().length > 0);
+}
+
+/** Select once, validate that source, then append current-machine terms only after nonempty validation. */
+export function resolveScanBaseline(options: ScanOptions, deps: ScanBaselineDeps): ResolvedScanBaseline {
+	const env = deps.env ?? process.env;
+	for (const value of [env.ZGW_SECURITY_BASELINE_FILE, env.ZIGMINI_PRIVATE_STRINGS]) {
+		if (value !== undefined && value.trim().length === 0) throw new ScanError("baseline_env_empty");
+	}
+	const source = resolveBaselineSource({ baselineFlag: options.baseline, env });
+	let file: BaselineFile | null = null;
+	let terms: readonly string[];
+	switch (source.kind) {
+		case "baseline": {
+			const result = readBaseline(source);
+			if (!result.ok) throw new ScanError(`baseline_${result.error}`, result.error === "missing" || result.error === "empty" ? 3 : 2);
+			file = result.file;
+			terms = file.terms;
+			break;
+		}
+		case "legacy-list":
+			deps.err(`${TEXT[deps.lang ?? "en"].legacy}\n`);
+			try { terms = parseList(readFileSync(source.path, "utf8")); }
+			catch (error) {
+				if (!(error instanceof Error) || !("code" in error)) throw error;
+				throw new ScanError(error.code === "ENOENT" ? "baseline_missing" : "baseline_unreadable", error.code === "ENOENT" ? 3 : 2);
+			}
+			if (terms.length === 0) throw new ScanError("baseline_empty", 3);
+			break;
+		case "missing": throw new ScanError("baseline_missing", 3);
+		case "hash-only": throw new ScanError("baseline_source_invalid");
+		default: {
+			const unreachable: never = source;
+			throw new ScanError(`baseline_source_invalid:${unreachable}`);
+		}
+	}
+	const machine = deps.machine ?? { home: homedir(), user: userInfo().username };
+	const automatic = machineTerms(machine);
+	return { source: source.kind, revision: file?.revision ?? null, file,
+		terms: [...terms, ...automatic.terms.filter((term) => !terms.includes(term))], home: automatic.home, user: machine.user };
+}
+export interface ScanResult {
+	readonly counts: { readonly total: number };
+	readonly findings?: readonly PrivateFinding[];
+	readonly allowedRepo?: number;
+	readonly hashes?: number | "absent";
+	/** Internal snapshot only. Never serialize a result or a finding directly. */
+	readonly redaction?: { readonly home: string; readonly set: PrivateSet };
+	readonly sync?: HashSyncCounts;
+}
+export interface HashSyncCounts {
+	readonly inputTerms: number;
+	readonly uniqueTerms: number;
+	readonly duplicates: number;
+	readonly excluded: Readonly<Record<HashSyncExclusion, number>>;
+	readonly exportedHashes: number;
+	readonly changed: boolean;
+}
+export type HashSyncExclusion = "tooShort" | "asciiShort" | "automatic" | "loopback" | "publicGithub";
+export interface HashSyncResult extends ScanResult { readonly sync: HashSyncCounts }
+
+/** D8 reasons are exclusive; automatic/public values take precedence over length. */
+export function hashSyncExclusion(term: string, baseline: ResolvedScanBaseline): HashSyncExclusion | null {
+	const value = normalizeTerm(term);
+	if ([baseline.home, baseline.user, baseline.file?.home, baseline.file?.user]
+		.some((automatic) => automatic !== undefined && normalizeTerm(automatic) === value)) return "automatic";
+	if (/^(?:(?:wss?|https?):\/\/)?(?:127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|\[::1\]|::1)(?::\d+)?\/?$/.test(value)) return "loopback";
+	if (value.replace(PUBLIC_ACCOUNT, "") !== value) return "publicGithub";
+	if ([...value].length < 8) return "tooShort";
+	if (/^[a-z]+$/.test(value) && value.length < 10) return "asciiShort";
+	return null;
+}
+
+/** Synchronize only the validated in-memory baseline; never scan, stage or commit. */
+export async function syncHashes(options: ScanOptions, target: ScanTarget, baseline: ResolvedScanBaseline): Promise<HashSyncResult> {
+	const scripts = join(target.root, "scripts"), file = join(scripts, "private-strings.hashes.json");
+	try {
+		const parent = lstatSync(scripts);
+		if (!parent.isDirectory()) throw new ScanError("hash_sync_scripts_invalid");
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+		mkdirSync(scripts);
+	}
+	let previous: string | null = null;
+	try {
+		const entry = lstatSync(file);
+		if (!entry.isFile()) throw new ScanError("hash_sync_file_invalid");
+		previous = readFileSync(file, "utf8");
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+	}
+	// Reuse the scanner's salt/hash validation, even for --prune. Invalid files fail closed.
+	const existing = loadPrivateSet(hashOnlySource(), file, { home: baseline.home, user: baseline.user }).hashes;
+	const terms = new Set(baseline.terms.map(normalizeTerm));
+	const excluded = { tooShort: 0, asciiShort: 0, automatic: 0, loopback: 0, publicGithub: 0 };
+	const hashes = new Set(options.prune ? [] : existing);
+	for (const term of terms) {
+		const reason = hashSyncExclusion(term, baseline);
+		if (reason === null) hashes.add(hashTerm(term));
+		else excluded[reason]++;
+	}
+	const text = `${JSON.stringify({ salt: HASH_SALT, hashes: [...hashes].sort() }, null, 2)}\n`;
+	const changed = text !== previous;
+	if (changed) {
+		const temporary = join(scripts, `.private-strings.hashes-${randomUUID()}.tmp`);
+		const fd = openSync(temporary, "wx", 0o600);
+		let renamed = false;
+		try {
+			try { writeFileSync(fd, text); fsyncSync(fd); }
+			finally { closeSync(fd); }
+			// A newly introduced symlink must not become the destination of the replacement.
+			try {
+				const current = lstatSync(file);
+				if (!current.isFile()) throw new ScanError("hash_sync_file_invalid");
+			} catch (error) {
+				if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+			}
+			renameSync(temporary, file);
+			renamed = true;
+		} finally { if (!renamed) unlinkSync(temporary); }
+	}
+	return { counts: { total: 0 }, hashes: hashes.size, sync: {
+		inputTerms: baseline.terms.length, uniqueTerms: terms.size, duplicates: baseline.terms.length - terms.size,
+		excluded, exportedHashes: hashes.size, changed,
+	} };
+}
+export interface RepositoryScanResult extends ScanResult {
+	readonly findings: readonly PrivateFinding[];
+	readonly allowedRepo: number;
+	readonly hashes: number | "absent";
+	readonly redaction: { readonly home: string; readonly set: PrivateSet };
+}
+
+/** Scan the selected snapshot, then apply repository permissions before counting or reporting. */
+export async function scanRepository(options: ScanOptions, target: ScanTarget, baseline: ResolvedScanBaseline): Promise<RepositoryScanResult> {
+	const machine = { home: baseline.home, user: baseline.user };
+	const loaded = loadPrivateSet(hashOnlySource(), join(target.root, "scripts/private-strings.hashes.json"), machine);
+	const set = { hashes: loaded.hashes, terms: baseline.terms };
+	const findings = [
+		...(options.scope === "git" ? [] : scanTracked(target.root, set)),
+		...(options.scope === "tracked" ? [] : scanGitObjects(target.gitDir, set, target.exceptions)),
+	];
+	const { kept, allowedRepo } = applyRepoAllow(findings, baseline.file?.allow ?? [], machine);
+	return { findings: kept, counts: { total: kept.length }, allowedRepo, hashes: loaded.hashCount,
+		redaction: { home: baseline.home, set: { hashes: set.hashes,
+			terms: [...baseline.terms, ...(baseline.file?.allow.map(({ value }) => value) ?? [])] } } };
+}
+
+export interface ScanReport {
+	readonly status: "complete" | "incomplete" | "not_scanned";
+	readonly didScan: boolean;
+	readonly source: ScanBaseline["source"] | null;
+	readonly revision: number | null;
+	readonly freshness: ScanFreshness | null;
+	readonly counts: ScanResult["counts"] | null;
+}
+
+/** Remove complete values before escaping terminal controls; never leave a value prefix. */
+export function redactScanLocation(file: string, redaction: NonNullable<ScanResult["redaction"]>): string {
+	const path = tildeHome(file, redaction.home).normalize("NFC");
+	const values = [...redaction.set.terms, ...findPrivate(path, redaction.set).map((hit) => hit.value)]
+		.filter((value) => value.length > 0).map((value) => value.normalize("NFC"));
+	const pattern = [...new Set(values)].sort((a, b) => b.length - a.length)
+		.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+	const safe = pattern.length === 0 ? path : path.replace(new RegExp(pattern, "gi"), "<redacted>");
+	return safe.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g,
+		(value) => `\\u${value.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+
+/** Project trusted metadata and safe locations, never values, tokens or baseline contents. */
+export function renderScanReport(report: ScanReport, options: ScanOptions, result: ScanResult | null): string {
+	const findings = result?.findings ?? [];
+	const byRule: Record<string, number> = {};
+	for (const finding of findings) byRule[finding.rule] = (byRule[finding.rule] ?? 0) + 1;
+	const summary = { type: "summary", ...report,
+		counts: report.counts === null ? null : { ...report.counts, byRule },
+		allowedRepo: result?.allowedRepo ?? null, hashes: result?.hashes ?? null,
+		...(result?.sync === undefined ? {} : { sync: result.sync }) };
+	const locations = options.quiet ? [] : findings.slice(0, options.json ? findings.length : 50).map((finding) => {
+		if (result?.redaction === undefined) throw new ScanError("report_redaction_missing");
+		return { type: "finding", rule: finding.rule, file: redactScanLocation(finding.file, result.redaction), line: finding.line ?? null };
+	});
+	if (options.json) return `${[...locations, summary].map((row) => JSON.stringify(row)).join("\n")}\n`;
+	const lines = [`SECURITY_FINDING_COUNTS ${JSON.stringify(summary.counts)}`,
+		...locations.map((location) => `${location.rule} ${location.file}:${location.line ?? "-"}`)];
+	if (result?.sync !== undefined) lines.push("Hash synchronization only; the repository was not scanned.");
+	if (!options.quiet && findings.length > 50) lines.push(`... ${findings.length} findings`);
+	lines.push(`SECURITY_SCAN_SUMMARY ${JSON.stringify(summary)}`);
+	return `${lines.join("\n")}\n`;
+}
+
+/** Exclusive creation also rejects symlinks and races after prepareScan's preflight. */
+export function reportScan(report: ScanReport, options: ScanOptions, result: ScanResult | null,
+	out: (text: string) => void = (text) => { process.stdout.write(text); }): void {
+	const text = renderScanReport(report, options, result);
+	if (options.out === undefined) out(text);
+	else writeFileSync(options.out, text, { flag: "wx", mode: 0o600 });
+}
+/** Later todos supply real baseline/probe/scan/sync/report adapters; no default adapter silently succeeds. */
+export interface ScanDeps<B extends ScanBaseline = ScanBaseline, R extends ScanResult = ScanResult> {
+	readonly lang: Language;
+	readonly out: (text: string) => void;
+	readonly err: (text: string) => void;
+	readonly prepare: (options: ScanOptions) => ScanTarget | Promise<ScanTarget>;
+	readonly baseline: (options: ScanOptions, target: ScanTarget) => B | Promise<B>;
+	readonly revision: (baseline: B) => Promise<ScanFreshness>;
+	readonly scan: (options: ScanOptions, target: ScanTarget, baseline: B) => Promise<R>;
+	readonly syncHashes: (options: ScanOptions, target: ScanTarget, baseline: B) => Promise<R>;
+	readonly report: (report: ScanReport, options: ScanOptions, result: R | null) => void | Promise<void>;
+}
+export function scanExitCode(total: number): 0 | 1 {
+	return total > 0 ? 1 : 0;
+}
+
+/** The orchestration boundary owns precedence: usage/input, baseline, freshness, execution, output. */
+export async function runScan<B extends ScanBaseline, R extends ScanResult>(options: ScanOptions | string, deps: ScanDeps<B, R>): Promise<ScanExitCode> {
+	try {
+		if (typeof options === "string") { deps.err(`${options}\n${scanHelp(deps.lang)}`); return 2; }
+		if (options.help) { deps.out(scanHelp(deps.lang)); return 0; }
+		let phase: "input" | "baseline" | "revision" | "execution" = "input";
+		let report: ScanReport = { status: "not_scanned", didScan: false, source: null, revision: null, freshness: null, counts: null };
+		let result: R | null = null;
+		let code: ScanExitCode;
+		try {
+			const target = await deps.prepare(options);
+			phase = "baseline";
+			const baseline = await deps.baseline(options, target);
+			report = { ...report, source: baseline.source, revision: baseline.revision };
+			phase = "revision";
+			const freshness = await deps.revision(baseline);
+			report = { ...report, freshness };
+			if (freshness !== "verified" && freshness !== "unchecked_offline") throw new ScanError(`baseline_${freshness}`, 3);
+			phase = "execution";
+			report = { ...report, status: "incomplete", didScan: !options.syncHashes };
+			result = options.syncHashes ? await deps.syncHashes(options, target, baseline) : await deps.scan(options, target, baseline);
+			report = { ...report, status: "complete", counts: result.counts };
+			code = options.syncHashes ? 0 : scanExitCode(result.counts.total);
+		} catch (error) {
+			code = phase === "baseline" || phase === "revision" ? (error instanceof ScanError ? error.exitCode : 2) : 2;
+			const reason = error instanceof ScanError ? error.code : `scan_${phase}_failed`;
+			deps.err(`${TEXT[deps.lang].error}: ${reason}\n`);
+		}
+		// Failed input validation must not send a report to an unvalidated or forbidden output path.
+		const reportOptions = phase === "input" ? { ...options, out: undefined } : options;
+		try { await deps.report(report, reportOptions, result); }
+		catch (error) {
+			// I/O error messages can contain private paths or values.
+			deps.err(`${TEXT[deps.lang].output}: ${error instanceof ScanError ? error.code : "scan_output_failed"}\n`);
+			return 2;
+		}
+		return code;
+	} catch {
+		// The final CLI boundary cannot report a broken stdout/stderr through that same stream.
+		return 2;
+	}
+}

package/src/cli/security-import.ts

@@ -0,0 +1,155 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { runtimePaths, securityBaselinePaths, type Env } from "../runtime/paths.ts";
+import { parseList } from "../security/repo-scan.ts";
+import { findPrivate, normalizeTerm, PUBLIC_ACCOUNT, tildeHome } from "../security/terms.ts";
+import type { FetchLike } from "./pair.ts";
+
+export interface ImportOptions {
+	readonly from?: string;
+	readonly dryRun: boolean;
+}
+
+interface ImportMarker {
+	readonly importedAt: string;
+	readonly count: number;
+	readonly source: string;
+}
+
+export interface ImportDeps {
+	readonly env: Env;
+	readonly fetch: FetchLike;
+	readonly readFile: (path: string) => Promise<string>;
+	readonly writeMarker: (path: string, marker: ImportMarker) => void;
+	readonly now: () => Date;
+	readonly out: (text: string) => void;
+	readonly err: (text: string) => void;
+}
+
+const USAGE = "zigmini security import-baseline [--from <file>] [--dry-run]";
+
+export function parseImportArgs(argv: readonly string[]): ImportOptions | string {
+	let from: string | undefined;
+	let dryRun = false;
+	for (let i = 0; i < argv.length; i++) {
+		switch (argv[i]) {
+			case "--from": {
+				const value = argv[++i];
+				if (from !== undefined || !value || value.startsWith("-") || /[\r\n\0]/.test(value)) return USAGE;
+				from = value;
+				break;
+			}
+			case "--dry-run":
+				if (dryRun) return USAGE;
+				dryRun = true;
+				break;
+			default: return USAGE;
+		}
+	}
+	return { ...(from === undefined ? {} : { from }), dryRun };
+}
+
+class ImportError extends Error {
+	constructor(readonly code: "gateway_down" | "gateway_response" | "revision_conflict" | "list_unreadable" | "receipt_failed") {
+		super(code);
+	}
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function revision(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** The list is the only input file; every gateway change crosses its revision-checked HTTP boundary. */
+export async function runImport(options: ImportOptions, deps: ImportDeps): Promise<number> {
+	const counts = { read: 0, added: 0, duplicates: 0, rejected: 0 };
+	const request = async (method: "GET" | "POST", body?: unknown) => {
+		let response: Awaited<ReturnType<FetchLike>>;
+		try {
+			response = await deps.fetch(`http://127.0.0.1:${runtimePaths(deps.env).ports.web}/api/settings/security-check/baseline`, {
+				method, redirect: "error", ...(body === undefined ? {} : {
+					headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+				}),
+			});
+		} catch { throw new ImportError("gateway_down"); }
+		let data: unknown;
+		try { data = await response.json(); }
+		catch { throw new ImportError("gateway_response"); }
+		if (!object(data)) throw new ImportError("gateway_response");
+		return { status: response.status, data };
+	};
+	try {
+		const home = deps.env.HOME || homedir();
+		const selected = options.from ?? securityBaselinePaths(deps.env).legacyPrivateStringsFile;
+		const source = resolve(selected.startsWith("~/") ? join(home, selected.slice(2)) : selected);
+		let text: string;
+		try { text = await deps.readFile(source); }
+		catch { throw new ImportError("list_unreadable"); }
+		const values = parseList(text).map(normalizeTerm);
+		counts.read = values.length;
+		const initial = await request("GET");
+		if (initial.status !== 200 || !revision(initial.data.revision) || !Array.isArray(initial.data.terms)) {
+			throw new ImportError("gateway_response");
+		}
+		const seen = new Set<string>();
+		for (const term of initial.data.terms) {
+			if (!object(term) || typeof term.value !== "string") throw new ImportError("gateway_response");
+			seen.add(term.value);
+		}
+		let expectedRevision = initial.data.revision;
+		for (const value of values) {
+			// Reuse the list predicate, including its public-account masking exception, without loading gateway state.
+			if (value.length < 3 || (!value.match(PUBLIC_ACCOUNT) &&
+				!findPrivate(value, { terms: [value], hashes: new Set() }).some((hit) => hit.rule === "private-list"))) {
+				counts.rejected++;
+				continue;
+			}
+			if (seen.has(value)) { counts.duplicates++; continue; }
+			seen.add(value);
+			if (options.dryRun) { counts.added++; continue; }
+			const response = await request("POST", { value, expectedRevision });
+			if (response.status === 400 && response.data.error === "term_duplicate") { counts.duplicates++; continue; }
+			if (response.status === 400 && response.data.error === "term_invalid") { counts.rejected++; continue; }
+			if (response.status === 409) throw new ImportError("revision_conflict");
+			if (response.status !== 200 || !revision(response.data.revision) || response.data.revision !== expectedRevision + 1) {
+				throw new ImportError("gateway_response");
+			}
+			expectedRevision = response.data.revision;
+			counts.added++;
+		}
+		if (!options.dryRun) {
+			try {
+				deps.writeMarker(join(runtimePaths(deps.env).secrets, "baseline-imported"), {
+					importedAt: deps.now().toISOString(), count: counts.added, source: tildeHome(source, home),
+				});
+			} catch { throw new ImportError("receipt_failed"); }
+		}
+		deps.out(`${JSON.stringify(counts)}\n`);
+		return 0;
+	} catch (error) {
+		// The CLI boundary never renders file contents, paths, response bodies or adapter error messages.
+		const code = error instanceof ImportError ? error.code : "gateway_response";
+		deps.out(`${JSON.stringify(counts)}\n`);
+		deps.err(code === "gateway_down" ? "게이트웨이가 켜져 있어야 가져올 수 있습니다.\n" : `security_import_${code}\n`);
+		return 2;
+	}
+}
+
+export function systemImportDeps(env: Env = process.env): ImportDeps {
+	return {
+		env, fetch: (url, init) => fetch(url, { ...init, signal: AbortSignal.timeout(10_000) }),
+		readFile: (path) => readFile(path, "utf8"),
+		writeMarker: (path, marker) => {
+			mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+			chmodSync(dirname(path), 0o700);
+			writeFileSync(path, JSON.stringify(marker) + "\n", { mode: 0o600 });
+			chmodSync(path, 0o600);
+		},
+		now: () => new Date(), out: (text) => process.stdout.write(text), err: (text) => process.stderr.write(text),
+	};
+}

package/src/compact.ts

@@ -0,0 +1,22 @@
+/**
+ * `/compact` (improvement 230): the gateway asks the engine to summarize the conversation's session now (RPC `compact`)
+ * and never sends the text to the model as a prompt.
+ */
+const COMPACT_DESCRIPTION: Text = {
+	en: "Summarize the conversation, e.g. /compact focus on decisions (sent directly to the engine by the gateway)",
+	ko: "대화 요약(압축)하기, 예: /compact 결정 사항 위주로 (게이트웨이가 엔진에 바로 요청함)",
+};
+
+export const COMPACT_COMMAND = {
+	name: "compact",
+	get description() { return say(COMPACT_DESCRIPTION); },
+	source: "extension",
+};
+
+/** The extra summary instructions of a `/compact` message ("" for none), or null when the text is not that command. */
+export function compactInstructions(text: string): string | null {
+	const match = /^\/compact(?:\s+([\s\S]*))?$/i.exec(text.trim());
+	return match ? (match[1] ?? "").trim() : null;
+}
+import { say, type Text } from "./server-text.ts";
+