@graphorin/cli 0.5.0

package/dist/commands/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","names":["server: Awaited<ReturnType<typeof createServer>> | undefined"],"sources":["../../src/commands/start.ts"],"sourcesContent":["/**\n * `graphorin start [--config <path>]`. Boots the standalone server.\n *\n * Exits 1 on every recoverable failure (missing pepper, unresolvable\n * SecretRef, missing encryption peer, migration error). The CLI never\n * prints raw secret values; failure messages reference the offending\n * config path + the suggested `graphorin doctor` follow-up (Phase 15).\n *\n * @packageDocumentation\n */\n\nimport process from 'node:process';\n\nimport { applyProcessHardening, RefuseToRunAsRootError } from '@graphorin/security';\nimport { ConfigInvalidError, createServer, GraphorinServerError } from '@graphorin/server';\n\nimport { loadConfig } from '../internal/load-config.js';\n\n/**\n * Selector for which `SecretsStore` flavour the server activates at\n * startup. Mirrors `--secrets-source` from DEC-136.\n *\n * @stable\n */\nexport type SecretsSourceFlag = 'auto' | 'keyring' | 'encrypted-file' | 'env';\n\n/**\n * @stable\n */\nexport interface StartCommandOptions {\n  readonly config?: string;\n  readonly host?: string;\n  readonly port?: number;\n  readonly logResolved?: boolean;\n  /**\n   * Override the `secrets.source` field of the loaded config. Mirrors\n   * the `--secrets-source <kind>` flag from DEC-136.\n   */\n  readonly secretsSource?: SecretsSourceFlag;\n  /**\n   * Refuse to fall back when the requested primary store is\n   * unavailable. Mirrors `--strict-secrets` from DEC-136.\n   */\n  readonly strictSecrets?: boolean;\n}\n\n/**\n * Programmatic entry — used both by the CLI binary and by tests so\n * the spawn cost of running the binary is paid only when an operator\n * actually invokes `graphorin start` from a shell.\n *\n * @stable\n */\nexport async function runStart(\n  options: StartCommandOptions = {},\n): Promise<{ readonly host: string; readonly port: number }> {\n  applyHardeningEarly();\n  const loaded = await loadConfig(options.config);\n  if (options.logResolved !== false) {\n    process.stderr.write(`[graphorin/cli] resolved config: ${loaded.path}\\n`);\n  }\n  const overrides = applyCliOverrides(loaded.config, options);\n\n  let server: Awaited<ReturnType<typeof createServer>> | undefined;\n  try {\n    server = await createServer({ config: overrides });\n  } catch (err) {\n    fatal(err);\n  }\n  if (server === undefined) process.exit(1);\n\n  const listening = await safeStart(server);\n  process.stderr.write(\n    `[graphorin/cli] @graphorin/server v${server.version} listening on http://${listening.host}:${listening.port}${server.config.server.basePath}\\n`,\n  );\n  installSignalHandlers(server);\n  return listening;\n}\n\n/**\n * Merge CLI flag overrides into the loaded `graphorin.config` payload.\n * Exported for unit tests so callers can assert the precedence rules\n * without spinning up a real server.\n *\n * @internal\n */\nexport function applyCliOverrides(\n  input: { readonly server?: unknown; readonly secrets?: unknown } | undefined,\n  options: StartCommandOptions,\n): Record<string, unknown> {\n  const next = { ...(input ?? {}) } as Record<string, unknown>;\n  const serverInput = (next.server as Record<string, unknown> | undefined) ?? {};\n  if (options.host !== undefined || options.port !== undefined) {\n    next.server = {\n      ...serverInput,\n      ...(options.host !== undefined ? { host: options.host } : {}),\n      ...(options.port !== undefined ? { port: options.port } : {}),\n    };\n  }\n  const secretsInput = (next.secrets as Record<string, unknown> | undefined) ?? {};\n  if (options.secretsSource !== undefined || options.strictSecrets !== undefined) {\n    next.secrets = {\n      ...secretsInput,\n      ...(options.secretsSource !== undefined ? { source: options.secretsSource } : {}),\n      ...(options.strictSecrets !== undefined ? { strict: options.strictSecrets } : {}),\n    };\n  }\n  return next;\n}\n\nasync function safeStart(server: Awaited<ReturnType<typeof createServer>>) {\n  try {\n    return await server.start();\n  } catch (err) {\n    fatal(err);\n  }\n  process.exit(1);\n}\n\nfunction fatal(err: unknown): never {\n  if (err instanceof ConfigInvalidError) {\n    process.stderr.write('[graphorin/cli] graphorin.config invalid:\\n');\n    for (const issue of err.issues) {\n      process.stderr.write(`  - ${issue.path.join('.') || '<root>'}: ${issue.message}\\n`);\n    }\n  } else if (err instanceof GraphorinServerError) {\n    process.stderr.write(`[graphorin/cli] ${err.kind}: ${err.message}\\n`);\n    if (err.hint !== undefined) {\n      process.stderr.write(`  hint: ${err.hint}\\n`);\n    }\n  } else if (err instanceof Error) {\n    process.stderr.write(`[graphorin/cli] ${err.message}\\n`);\n  } else {\n    process.stderr.write(`[graphorin/cli] unknown error: ${String(err)}\\n`);\n  }\n  process.exit(1);\n}\n\n/**\n * Apply the standard hardening hooks before the server bootstraps.\n * Failures (e.g. running as root on Linux/macOS) abort the start with\n * a documented exit code.\n *\n * @internal\n */\nexport function applyHardeningEarly(): void {\n  try {\n    applyProcessHardening({});\n  } catch (err) {\n    if (err instanceof RefuseToRunAsRootError) {\n      process.stderr.write(`[graphorin/cli] ${err.message}\\n`);\n      process.stderr.write(\n        '[graphorin/cli] hint: drop privileges (systemd User=, k8s runAsNonRoot, docker --user) and retry.\\n',\n      );\n      process.exit(1);\n    }\n    throw err;\n  }\n}\n\nfunction installSignalHandlers(server: Awaited<ReturnType<typeof createServer>>): void {\n  let shuttingDown = false;\n  const onSignal = (signal: NodeJS.Signals) => {\n    if (shuttingDown) return;\n    shuttingDown = true;\n    process.stderr.write(`[graphorin/cli] received ${signal}; draining...\\n`);\n    server\n      .stop()\n      .then(() => {\n        process.stderr.write('[graphorin/cli] graceful shutdown complete\\n');\n        process.exit(0);\n      })\n      .catch((err) => {\n        process.stderr.write(`[graphorin/cli] shutdown error: ${(err as Error).message}\\n`);\n        process.exit(1);\n      });\n  };\n  process.once('SIGTERM', onSignal);\n  process.once('SIGINT', onSignal);\n}\n"],"mappings":"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"}

package/dist/commands/storage.d.ts

@@ -0,0 +1,110 @@
+import { CommonOutputOptions } from "../internal/output.js";
+
+//#region src/commands/storage.d.ts
+
+/** @stable */
+interface StorageCommonOptions extends CommonOutputOptions {
+  readonly config?: string;
+}
+/** @stable */
+interface StorageStatusResult {
+  readonly path: string;
+  readonly mode: 'lib' | 'server';
+  readonly encryption: {
+    readonly enabled: boolean;
+    readonly cipher?: string;
+  };
+  readonly cipherPeer: {
+    readonly installed: boolean;
+    readonly hint?: string;
+  };
+  readonly mainDb: {
+    readonly exists: boolean;
+    readonly sizeBytes?: number;
+  };
+  readonly walFile: {
+    readonly exists: boolean;
+    readonly sizeBytes?: number;
+  };
+  readonly auditDb: {
+    readonly enabled: boolean;
+    readonly path?: string;
+    readonly exists?: boolean;
+  };
+}
+/** @stable */
+declare function runStorageStatus(options?: StorageCommonOptions): Promise<StorageStatusResult>;
+/** @stable */
+interface StorageEncryptOptions extends StorageCommonOptions {
+  /** SecretRef URI for the new passphrase. */
+  readonly passphraseFrom: string;
+  /**
+   * Optional explicit target path for the encrypted output. Default:
+   * `<storage.path>.encrypted`.
+   */
+  readonly targetPath?: string;
+  /**
+   * If `true`, atomically swap the encrypted target into the
+   * `storage.path` location after the integrity check, leaving the
+   * original under `<storage.path>.bak.<timestamp>`. Default `false`.
+   */
+  readonly swap?: boolean;
+}
+/** @stable */
+interface StorageEncryptResult {
+  readonly sourcePath: string;
+  readonly targetPath: string;
+  readonly cipher: string;
+  readonly integrityOk: boolean;
+  readonly swap?: {
+    readonly originalRenamedTo: string;
+  };
+}
+/**
+ * `graphorin storage encrypt --passphrase-from <ref>` — encrypt a
+ * previously unencrypted SQLite store. Delegates to the optional Phase
+ * 16 sub-pack `@graphorin/store-sqlite-encrypted` once installed; when
+ * the sub-pack is missing the CLI exits `2` (`UNSUPPORTED`) with an
+ * actionable hint.
+ *
+ * @stable
+ */
+declare function runStorageEncrypt(options: StorageEncryptOptions): Promise<StorageEncryptResult>;
+/** @stable */
+interface StorageRekeyOptions extends StorageCommonOptions {
+  readonly oldPassphraseFrom: string;
+  readonly newPassphraseFrom: string;
+}
+/** @stable */
+interface StorageRekeyResult {
+  readonly path: string;
+  readonly cipher: string;
+  readonly integrityOk: boolean;
+}
+/** @stable */
+declare function runStorageRekey(options: StorageRekeyOptions): Promise<StorageRekeyResult>;
+/** @stable */
+interface StorageCleanupBackupsOptions extends StorageCommonOptions {
+  /**
+   * Skip the actual delete; print what would be removed. Default `false`.
+   * Tests pass `true` to assert the discovery without touching files.
+   */
+  readonly dryRun?: boolean;
+}
+/** @stable */
+interface StorageCleanupBackupsResult {
+  readonly directory: string;
+  readonly removed: ReadonlyArray<string>;
+  readonly dryRun: boolean;
+}
+/**
+ * Drop stale `.bak`, `.bak.<ts>`, and `.tmp.<ts>` siblings of the
+ * configured storage path. Useful after `encrypt` / `rekey` runs that
+ * leave intermediate copies around.
+ *
+ * @stable
+ */
+declare function runStorageCleanupBackups(options?: StorageCleanupBackupsOptions): Promise<StorageCleanupBackupsResult>;
+//#endregion
+export { StorageCleanupBackupsOptions, StorageCleanupBackupsResult, StorageCommonOptions, StorageEncryptOptions, StorageRekeyOptions, StorageStatusResult, runStorageCleanupBackups, runStorageEncrypt, runStorageRekey, runStorageStatus };
+//# sourceMappingURL=storage.d.ts.map

package/dist/commands/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","names":[],"sources":["../../src/commands/storage.ts"],"sourcesContent":[],"mappings":";;;;AAkRA;AAasB,UApPL,oBAAA,SAA6B,mBAoPA,CAAA;EACnC,SAAA,MAAA,CAAA,EAAA,MAAA;;;AACD,UAjPO,mBAAA,CAiPP;;;;;;;;;;;;;;;;;;;;;;;;;;iBAlOY,gBAAA,WACX,uBACR,QAAQ;;UA+DM,qBAAA,SAA8B;;;;;;;;;;;;;;;;UAiB9B,oBAAA;;;;;;;;;;;;;;;;;;iBAiBK,iBAAA,UACX,wBACR,QAAQ;;UA8CM,mBAAA,SAA4B;;;;;UAM5B,kBAAA;;;;;;iBAOK,eAAA,UAAyB,sBAAsB,QAAQ;;UA0C5D,4BAAA,SAAqC;;;;;;;;UASrC,2BAAA;;oBAEG;;;;;;;;;;iBAWE,wBAAA,WACX,+BACR,QAAQ"}

package/dist/commands/storage.js

@@ -0,0 +1,274 @@
+import { brand, defaultPrintSink, emitReport, statusMarker } from "../internal/output.js";
+import { EXIT_CODES } from "../internal/exit.js";
+import { loadConfig } from "../internal/load-config.js";
+import { readdir, stat, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import process from "node:process";
+import { resolveSecret } from "@graphorin/security";
+import { parseServerConfig } from "@graphorin/server";
+
+//#region src/commands/storage.ts
+/**
+* `graphorin storage` — manage the SQLite store and its encryption-
+* at-rest opt-in.
+*
+* Surface (per Phase 15 § Storage):
+*
+*  - `graphorin storage status` — reports cipher peer + WAL + size +
+*    encryption mode.
+*  - `graphorin storage encrypt --passphrase-from <ref>` — opt-in
+*    encryption migration. Requires the `@graphorin/store-sqlite-
+*    encrypted` sub-pack from Phase 16.
+*  - `graphorin storage rekey --new-passphrase-from <ref>` — re-key
+*    an already-encrypted DB.
+*  - `graphorin storage cleanup-backups` — drop stale `.bak` /
+*    `.bak.<ts>` files left by previous encrypt / rekey runs.
+*
+* `encrypt`, `rekey`, and `cleanup-backups` need the cipher peer
+* (`better-sqlite3-multiple-ciphers`) which ships in the optional
+* Phase 16 sub-pack. When the peer is missing the CLI exits `2`
+* (`UNSUPPORTED`) with an actionable hint instead of silently
+* doing nothing.
+*
+* @packageDocumentation
+*/
+/** @stable */
+async function runStorageStatus(options = {}) {
+	const loaded = await loadConfig(options.config);
+	const config = parseServerConfig(loaded.config);
+	const cipherPeer = await probeCipherPeer();
+	const mainDb = await statSafely(resolveStoragePath(config.storage.path));
+	const walFile = await statSafely(`${resolveStoragePath(config.storage.path)}-wal`);
+	let auditPath;
+	let auditExists;
+	if (config.audit.enabled) {
+		auditPath = resolveStoragePath(config.audit.path ?? deriveAuditPath(config.storage.path));
+		auditExists = (await statSafely(auditPath)).exists;
+	}
+	const out = Object.freeze({
+		path: resolveStoragePath(config.storage.path),
+		mode: config.storage.mode,
+		encryption: Object.freeze({
+			enabled: config.storage.encryption.enabled,
+			...config.storage.encryption.cipher !== void 0 ? { cipher: config.storage.encryption.cipher } : {}
+		}),
+		cipherPeer: Object.freeze({
+			installed: cipherPeer.installed,
+			...cipherPeer.hint !== void 0 ? { hint: cipherPeer.hint } : {}
+		}),
+		mainDb: Object.freeze({
+			exists: mainDb.exists,
+			...mainDb.size !== void 0 ? { sizeBytes: mainDb.size } : {}
+		}),
+		walFile: Object.freeze({
+			exists: walFile.exists,
+			...walFile.size !== void 0 ? { sizeBytes: walFile.size } : {}
+		}),
+		auditDb: Object.freeze({
+			enabled: config.audit.enabled,
+			...auditPath !== void 0 ? { path: auditPath } : {},
+			...auditExists !== void 0 ? { exists: auditExists } : {}
+		})
+	});
+	emitReport(options, out, () => {
+		const print = options.print ?? defaultPrintSink;
+		print(brand(`storage status (${loaded.path})`));
+		print(`  ${marker(out.mainDb.exists)} main:    ${out.path} (${formatSize(out.mainDb.sizeBytes)})`);
+		print(`  ${marker(out.walFile.exists)} wal:     ${out.path}-wal (${formatSize(out.walFile.sizeBytes)})`);
+		print(`  ${marker(out.encryption.enabled)} encryption: ${out.encryption.enabled ? `enabled (cipher=${out.encryption.cipher ?? "sqlcipher"})` : "disabled"}`);
+		print(`  ${marker(out.cipherPeer.installed)} cipher peer (better-sqlite3-multiple-ciphers): ${out.cipherPeer.installed ? "installed" : "missing"}`);
+		if (out.cipherPeer.hint !== void 0) print(`        -> ${out.cipherPeer.hint}`);
+		if (out.auditDb.enabled) print(`  ${marker(out.auditDb.exists === true)} audit.db: ${out.auditDb.path}`);
+	});
+	return out;
+}
+/**
+* `graphorin storage encrypt --passphrase-from <ref>` — encrypt a
+* previously unencrypted SQLite store. Delegates to the optional Phase
+* 16 sub-pack `@graphorin/store-sqlite-encrypted` once installed; when
+* the sub-pack is missing the CLI exits `2` (`UNSUPPORTED`) with an
+* actionable hint.
+*
+* @stable
+*/
+async function runStorageEncrypt(options) {
+	const subpack = await loadEncryptedSubpack();
+	if (subpack === null) return failUnsupported(options, `'graphorin storage encrypt' requires the optional sub-pack '@graphorin/store-sqlite-encrypted' (Phase 16) and the cipher peer 'better-sqlite3-multiple-ciphers'.`, "Install @graphorin/store-sqlite-encrypted (which pulls the cipher peer transitively) before running this command.");
+	const sourcePath = resolveStoragePath(parseServerConfig((await loadConfig(options.config)).config).storage.path);
+	const targetPath = options.targetPath ?? `${sourcePath}.encrypted`;
+	const passphrase = await resolvePassphraseRef(options.passphraseFrom);
+	try {
+		const result = await passphrase.use((raw) => subpack.encryptDatabase({
+			sourcePath,
+			targetPath,
+			passphrase: raw,
+			...options.swap === true ? { swap: true } : {},
+			overwriteTarget: false
+		}));
+		const out = Object.freeze({
+			sourcePath,
+			targetPath: result.targetPath,
+			cipher: result.cipher,
+			integrityOk: result.integrityCheck.ok,
+			...result.swap !== void 0 ? { swap: result.swap } : {}
+		});
+		emitReport(options, out, () => {
+			const print = options.print ?? defaultPrintSink;
+			print(brand(`encrypt: ${out.sourcePath} -> ${out.targetPath} (cipher=${out.cipher})`));
+			print(`  ${marker(out.integrityOk)} cipher_integrity_check`);
+			if (out.swap !== void 0) print(`  ${statusMarker("ok")} swapped; original kept at ${out.swap.originalRenamedTo}`);
+		});
+		return out;
+	} finally {
+		passphrase.dispose();
+	}
+}
+/** @stable */
+async function runStorageRekey(options) {
+	const subpack = await loadEncryptedSubpack();
+	if (subpack === null) return failUnsupported(options, `'graphorin storage rekey' requires the optional sub-pack '@graphorin/store-sqlite-encrypted' (Phase 16).`, "Install @graphorin/store-sqlite-encrypted before running this command.");
+	const path = resolveStoragePath(parseServerConfig((await loadConfig(options.config)).config).storage.path);
+	const oldPassphrase = await resolvePassphraseRef(options.oldPassphraseFrom);
+	const newPassphrase = await resolvePassphraseRef(options.newPassphraseFrom);
+	try {
+		const result = await oldPassphrase.use((oldRaw) => newPassphrase.use((newRaw) => subpack.rekeyDatabase({
+			path,
+			oldPassphrase: oldRaw,
+			newPassphrase: newRaw
+		})));
+		const out = Object.freeze({
+			path: result.path,
+			cipher: result.cipher,
+			integrityOk: result.integrityCheck.ok
+		});
+		emitReport(options, out, () => {
+			const print = options.print ?? defaultPrintSink;
+			print(brand(`rekey: ${out.path} (cipher=${out.cipher})`));
+			print(`  ${marker(out.integrityOk)} cipher_integrity_check`);
+		});
+		return out;
+	} finally {
+		oldPassphrase.dispose();
+		newPassphrase.dispose();
+	}
+}
+/**
+* Drop stale `.bak`, `.bak.<ts>`, and `.tmp.<ts>` siblings of the
+* configured storage path. Useful after `encrypt` / `rekey` runs that
+* leave intermediate copies around.
+*
+* @stable
+*/
+async function runStorageCleanupBackups(options = {}) {
+	const dbPath = resolveStoragePath(parseServerConfig((await loadConfig(options.config)).config).storage.path);
+	const dir = dirname(dbPath);
+	const basename = dbPath.split("/").pop() ?? "";
+	let entries;
+	try {
+		entries = await readdir(dir);
+	} catch (err) {
+		throw new Error(`[graphorin/cli] cannot read storage directory '${dir}': ${err.message}`);
+	}
+	const candidates = entries.filter((name) => isStaleBackup(basename, name));
+	const removed = [];
+	for (const name of candidates) {
+		const full = `${dir}/${name}`;
+		if (options.dryRun !== true) try {
+			await unlink(full);
+			removed.push(full);
+		} catch {}
+		else removed.push(full);
+	}
+	const out = Object.freeze({
+		directory: dir,
+		removed: Object.freeze(removed),
+		dryRun: options.dryRun === true
+	});
+	emitReport(options, out, () => {
+		const print = options.print ?? defaultPrintSink;
+		if (out.removed.length === 0) {
+			print(brand(`no stale backups found in ${dir}.`));
+			return;
+		}
+		print(brand(`${out.dryRun ? "would remove" : "removed"} ${out.removed.length} stale backup file(s) in ${dir}:`));
+		for (const name of out.removed) print(`  - ${name}`);
+	});
+	return out;
+}
+function isStaleBackup(baseName, candidate) {
+	if (candidate === baseName) return false;
+	if (!candidate.startsWith(baseName)) return false;
+	const suffix = candidate.slice(baseName.length);
+	if (suffix === ".bak") return true;
+	if (/^\.bak\.\d+$/.test(suffix)) return true;
+	if (/^\.tmp\.\d+$/.test(suffix)) return true;
+	return false;
+}
+async function probeCipherPeer() {
+	try {
+		await import("better-sqlite3-multiple-ciphers");
+		return Object.freeze({ installed: true });
+	} catch {
+		return Object.freeze({
+			installed: false,
+			hint: "install '@graphorin/store-sqlite-encrypted' (Phase 16) which transitively installs the cipher peer."
+		});
+	}
+}
+/** @internal */
+async function loadEncryptedSubpack() {
+	try {
+		const mod = await import("@graphorin/store-sqlite-encrypted");
+		if (typeof mod?.encryptDatabase === "function" && typeof mod?.rekeyDatabase === "function") return mod;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/** @internal */
+async function resolvePassphraseRef(ref) {
+	try {
+		return await resolveSecret(ref);
+	} catch (err) {
+		throw new Error(`[graphorin/cli] failed to resolve storage passphrase '${ref}': ${err.message}`, { cause: err });
+	}
+}
+async function statSafely(path) {
+	try {
+		return {
+			exists: true,
+			size: (await stat(path)).size
+		};
+	} catch {
+		return { exists: false };
+	}
+}
+function resolveStoragePath(target) {
+	return isAbsolute(target) ? target : resolve(target);
+}
+function deriveAuditPath(storagePath) {
+	const idx = storagePath.lastIndexOf("/");
+	if (idx < 0) return "audit.db";
+	return `${storagePath.slice(0, idx)}/audit.db`;
+}
+function formatSize(bytes) {
+	if (bytes === void 0) return "missing";
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+	return `${(bytes / (1024 * 1024)).toFixed(2)} MiB`;
+}
+function marker(ok) {
+	return ok ? statusMarker("ok") : statusMarker("warn");
+}
+function failUnsupported(options, message, hint) {
+	const print = options.print ?? defaultPrintSink;
+	print(brand(message));
+	print(brand(`hint: ${hint}`));
+	process.exit(EXIT_CODES.UNSUPPORTED);
+	/* c8 ignore next */
+	throw new Error("unreachable");
+}
+
+//#endregion
+export { runStorageCleanupBackups, runStorageEncrypt, runStorageRekey, runStorageStatus };
+//# sourceMappingURL=storage.js.map

package/dist/commands/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","names":["auditPath: string | undefined","auditExists: boolean | undefined","out: StorageStatusResult","out: StorageEncryptResult","out: StorageRekeyResult","entries: string[]","removed: string[]","out: StorageCleanupBackupsResult"],"sources":["../../src/commands/storage.ts"],"sourcesContent":["/**\n * `graphorin storage` — manage the SQLite store and its encryption-\n * at-rest opt-in.\n *\n * Surface (per Phase 15 § Storage):\n *\n *  - `graphorin storage status` — reports cipher peer + WAL + size +\n *    encryption mode.\n *  - `graphorin storage encrypt --passphrase-from <ref>` — opt-in\n *    encryption migration. Requires the `@graphorin/store-sqlite-\n *    encrypted` sub-pack from Phase 16.\n *  - `graphorin storage rekey --new-passphrase-from <ref>` — re-key\n *    an already-encrypted DB.\n *  - `graphorin storage cleanup-backups` — drop stale `.bak` /\n *    `.bak.<ts>` files left by previous encrypt / rekey runs.\n *\n * `encrypt`, `rekey`, and `cleanup-backups` need the cipher peer\n * (`better-sqlite3-multiple-ciphers`) which ships in the optional\n * Phase 16 sub-pack. When the peer is missing the CLI exits `2`\n * (`UNSUPPORTED`) with an actionable hint instead of silently\n * doing nothing.\n *\n * @packageDocumentation\n */\n\nimport { readdir, stat, unlink } from 'node:fs/promises';\nimport { dirname, isAbsolute, resolve } from 'node:path';\nimport process from 'node:process';\n\nimport { resolveSecret, type SecretValue } from '@graphorin/security';\nimport { parseServerConfig } from '@graphorin/server';\n\nimport { EXIT_CODES } from '../internal/exit.js';\nimport { loadConfig } from '../internal/load-config.js';\nimport {\n  brand,\n  type CommonOutputOptions,\n  defaultPrintSink,\n  emitReport,\n  statusMarker,\n} from '../internal/output.js';\n\n/** @stable */\nexport interface StorageCommonOptions extends CommonOutputOptions {\n  readonly config?: string;\n}\n\n/** @stable */\nexport interface StorageStatusResult {\n  readonly path: string;\n  readonly mode: 'lib' | 'server';\n  readonly encryption: { readonly enabled: boolean; readonly cipher?: string };\n  readonly cipherPeer: { readonly installed: boolean; readonly hint?: string };\n  readonly mainDb: { readonly exists: boolean; readonly sizeBytes?: number };\n  readonly walFile: { readonly exists: boolean; readonly sizeBytes?: number };\n  readonly auditDb: {\n    readonly enabled: boolean;\n    readonly path?: string;\n    readonly exists?: boolean;\n  };\n}\n\n/** @stable */\nexport async function runStorageStatus(\n  options: StorageCommonOptions = {},\n): Promise<StorageStatusResult> {\n  const loaded = await loadConfig(options.config);\n  const config = parseServerConfig(loaded.config);\n  const cipherPeer = await probeCipherPeer();\n  const mainDb = await statSafely(resolveStoragePath(config.storage.path));\n  const walFile = await statSafely(`${resolveStoragePath(config.storage.path)}-wal`);\n  let auditPath: string | undefined;\n  let auditExists: boolean | undefined;\n  if (config.audit.enabled) {\n    auditPath = resolveStoragePath(config.audit.path ?? deriveAuditPath(config.storage.path));\n    auditExists = (await statSafely(auditPath)).exists;\n  }\n  const out: StorageStatusResult = Object.freeze({\n    path: resolveStoragePath(config.storage.path),\n    mode: config.storage.mode,\n    encryption: Object.freeze({\n      enabled: config.storage.encryption.enabled,\n      ...(config.storage.encryption.cipher !== undefined\n        ? { cipher: config.storage.encryption.cipher }\n        : {}),\n    }),\n    cipherPeer: Object.freeze({\n      installed: cipherPeer.installed,\n      ...(cipherPeer.hint !== undefined ? { hint: cipherPeer.hint } : {}),\n    }),\n    mainDb: Object.freeze({\n      exists: mainDb.exists,\n      ...(mainDb.size !== undefined ? { sizeBytes: mainDb.size } : {}),\n    }),\n    walFile: Object.freeze({\n      exists: walFile.exists,\n      ...(walFile.size !== undefined ? { sizeBytes: walFile.size } : {}),\n    }),\n    auditDb: Object.freeze({\n      enabled: config.audit.enabled,\n      ...(auditPath !== undefined ? { path: auditPath } : {}),\n      ...(auditExists !== undefined ? { exists: auditExists } : {}),\n    }),\n  });\n  emitReport(options, out, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand(`storage status (${loaded.path})`));\n    print(\n      `  ${marker(out.mainDb.exists)} main:    ${out.path} (${formatSize(out.mainDb.sizeBytes)})`,\n    );\n    print(\n      `  ${marker(out.walFile.exists)} wal:     ${out.path}-wal (${formatSize(out.walFile.sizeBytes)})`,\n    );\n    print(\n      `  ${marker(out.encryption.enabled)} encryption: ${out.encryption.enabled ? `enabled (cipher=${out.encryption.cipher ?? 'sqlcipher'})` : 'disabled'}`,\n    );\n    print(\n      `  ${marker(out.cipherPeer.installed)} cipher peer (better-sqlite3-multiple-ciphers): ${out.cipherPeer.installed ? 'installed' : 'missing'}`,\n    );\n    if (out.cipherPeer.hint !== undefined) print(`        -> ${out.cipherPeer.hint}`);\n    if (out.auditDb.enabled) {\n      print(`  ${marker(out.auditDb.exists === true)} audit.db: ${out.auditDb.path}`);\n    }\n  });\n  return out;\n}\n\n/** @stable */\nexport interface StorageEncryptOptions extends StorageCommonOptions {\n  /** SecretRef URI for the new passphrase. */\n  readonly passphraseFrom: string;\n  /**\n   * Optional explicit target path for the encrypted output. Default:\n   * `<storage.path>.encrypted`.\n   */\n  readonly targetPath?: string;\n  /**\n   * If `true`, atomically swap the encrypted target into the\n   * `storage.path` location after the integrity check, leaving the\n   * original under `<storage.path>.bak.<timestamp>`. Default `false`.\n   */\n  readonly swap?: boolean;\n}\n\n/** @stable */\nexport interface StorageEncryptResult {\n  readonly sourcePath: string;\n  readonly targetPath: string;\n  readonly cipher: string;\n  readonly integrityOk: boolean;\n  readonly swap?: { readonly originalRenamedTo: string };\n}\n\n/**\n * `graphorin storage encrypt --passphrase-from <ref>` — encrypt a\n * previously unencrypted SQLite store. Delegates to the optional Phase\n * 16 sub-pack `@graphorin/store-sqlite-encrypted` once installed; when\n * the sub-pack is missing the CLI exits `2` (`UNSUPPORTED`) with an\n * actionable hint.\n *\n * @stable\n */\nexport async function runStorageEncrypt(\n  options: StorageEncryptOptions,\n): Promise<StorageEncryptResult> {\n  const subpack = await loadEncryptedSubpack();\n  if (subpack === null) {\n    return failUnsupported(\n      options,\n      `'graphorin storage encrypt' requires the optional sub-pack '@graphorin/store-sqlite-encrypted' (Phase 16) and the cipher peer 'better-sqlite3-multiple-ciphers'.`,\n      'Install @graphorin/store-sqlite-encrypted (which pulls the cipher peer transitively) before running this command.',\n    );\n  }\n  const loaded = await loadConfig(options.config);\n  const config = parseServerConfig(loaded.config);\n  const sourcePath = resolveStoragePath(config.storage.path);\n  const targetPath = options.targetPath ?? `${sourcePath}.encrypted`;\n  const passphrase = await resolvePassphraseRef(options.passphraseFrom);\n  try {\n    const result = await passphrase.use((raw) =>\n      subpack.encryptDatabase({\n        sourcePath,\n        targetPath,\n        passphrase: raw,\n        ...(options.swap === true ? { swap: true } : {}),\n        overwriteTarget: false,\n      }),\n    );\n    const out: StorageEncryptResult = Object.freeze({\n      sourcePath,\n      targetPath: result.targetPath,\n      cipher: result.cipher,\n      integrityOk: result.integrityCheck.ok,\n      ...(result.swap !== undefined ? { swap: result.swap } : {}),\n    });\n    emitReport(options, out, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(brand(`encrypt: ${out.sourcePath} -> ${out.targetPath} (cipher=${out.cipher})`));\n      print(`  ${marker(out.integrityOk)} cipher_integrity_check`);\n      if (out.swap !== undefined) {\n        print(`  ${statusMarker('ok')} swapped; original kept at ${out.swap.originalRenamedTo}`);\n      }\n    });\n    return out;\n  } finally {\n    passphrase.dispose();\n  }\n}\n\n/** @stable */\nexport interface StorageRekeyOptions extends StorageCommonOptions {\n  readonly oldPassphraseFrom: string;\n  readonly newPassphraseFrom: string;\n}\n\n/** @stable */\nexport interface StorageRekeyResult {\n  readonly path: string;\n  readonly cipher: string;\n  readonly integrityOk: boolean;\n}\n\n/** @stable */\nexport async function runStorageRekey(options: StorageRekeyOptions): Promise<StorageRekeyResult> {\n  const subpack = await loadEncryptedSubpack();\n  if (subpack === null) {\n    return failUnsupported(\n      options,\n      `'graphorin storage rekey' requires the optional sub-pack '@graphorin/store-sqlite-encrypted' (Phase 16).`,\n      'Install @graphorin/store-sqlite-encrypted before running this command.',\n    );\n  }\n  const loaded = await loadConfig(options.config);\n  const config = parseServerConfig(loaded.config);\n  const path = resolveStoragePath(config.storage.path);\n  const oldPassphrase = await resolvePassphraseRef(options.oldPassphraseFrom);\n  const newPassphrase = await resolvePassphraseRef(options.newPassphraseFrom);\n  try {\n    const result = await oldPassphrase.use((oldRaw) =>\n      newPassphrase.use((newRaw) =>\n        subpack.rekeyDatabase({\n          path,\n          oldPassphrase: oldRaw,\n          newPassphrase: newRaw,\n        }),\n      ),\n    );\n    const out: StorageRekeyResult = Object.freeze({\n      path: result.path,\n      cipher: result.cipher,\n      integrityOk: result.integrityCheck.ok,\n    });\n    emitReport(options, out, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(brand(`rekey: ${out.path} (cipher=${out.cipher})`));\n      print(`  ${marker(out.integrityOk)} cipher_integrity_check`);\n    });\n    return out;\n  } finally {\n    oldPassphrase.dispose();\n    newPassphrase.dispose();\n  }\n}\n\n/** @stable */\nexport interface StorageCleanupBackupsOptions extends StorageCommonOptions {\n  /**\n   * Skip the actual delete; print what would be removed. Default `false`.\n   * Tests pass `true` to assert the discovery without touching files.\n   */\n  readonly dryRun?: boolean;\n}\n\n/** @stable */\nexport interface StorageCleanupBackupsResult {\n  readonly directory: string;\n  readonly removed: ReadonlyArray<string>;\n  readonly dryRun: boolean;\n}\n\n/**\n * Drop stale `.bak`, `.bak.<ts>`, and `.tmp.<ts>` siblings of the\n * configured storage path. Useful after `encrypt` / `rekey` runs that\n * leave intermediate copies around.\n *\n * @stable\n */\nexport async function runStorageCleanupBackups(\n  options: StorageCleanupBackupsOptions = {},\n): Promise<StorageCleanupBackupsResult> {\n  const loaded = await loadConfig(options.config);\n  const config = parseServerConfig(loaded.config);\n  const dbPath = resolveStoragePath(config.storage.path);\n  const dir = dirname(dbPath);\n  const basename = dbPath.split('/').pop() ?? '';\n  let entries: string[];\n  try {\n    entries = await readdir(dir);\n  } catch (err) {\n    throw new Error(\n      `[graphorin/cli] cannot read storage directory '${dir}': ${(err as Error).message}`,\n    );\n  }\n  const candidates = entries.filter((name) => isStaleBackup(basename, name));\n  const removed: string[] = [];\n  for (const name of candidates) {\n    const full = `${dir}/${name}`;\n    if (options.dryRun !== true) {\n      try {\n        await unlink(full);\n        removed.push(full);\n      } catch {\n        // best-effort cleanup; surface in summary\n      }\n    } else {\n      removed.push(full);\n    }\n  }\n  const out: StorageCleanupBackupsResult = Object.freeze({\n    directory: dir,\n    removed: Object.freeze(removed),\n    dryRun: options.dryRun === true,\n  });\n  emitReport(options, out, () => {\n    const print = options.print ?? defaultPrintSink;\n    if (out.removed.length === 0) {\n      print(brand(`no stale backups found in ${dir}.`));\n      return;\n    }\n    print(\n      brand(\n        `${out.dryRun ? 'would remove' : 'removed'} ${out.removed.length} stale backup file(s) in ${dir}:`,\n      ),\n    );\n    for (const name of out.removed) print(`  - ${name}`);\n  });\n  return out;\n}\n\nfunction isStaleBackup(baseName: string, candidate: string): boolean {\n  if (candidate === baseName) return false;\n  if (!candidate.startsWith(baseName)) return false;\n  const suffix = candidate.slice(baseName.length);\n  if (suffix === '.bak') return true;\n  if (/^\\.bak\\.\\d+$/.test(suffix)) return true;\n  if (/^\\.tmp\\.\\d+$/.test(suffix)) return true;\n  return false;\n}\n\nasync function probeCipherPeer(): Promise<{\n  readonly installed: boolean;\n  readonly hint?: string;\n}> {\n  try {\n    const moduleName = 'better-sqlite3-multiple-ciphers';\n    await import(/* @vite-ignore */ moduleName);\n    return Object.freeze({ installed: true });\n  } catch {\n    return Object.freeze({\n      installed: false,\n      hint: \"install '@graphorin/store-sqlite-encrypted' (Phase 16) which transitively installs the cipher peer.\",\n    });\n  }\n}\n\n/**\n * Encryption sub-pack surface consumed by the CLI runners. Declared\n * here so the dynamic-import path stays typed without forcing the CLI\n * to take a hard dependency on the optional package.\n *\n * @internal\n */\ninterface EncryptedSubpack {\n  encryptDatabase(args: {\n    sourcePath: string;\n    targetPath: string;\n    passphrase: string;\n    swap?: boolean;\n    overwriteTarget?: boolean;\n  }): Promise<{\n    sourcePath: string;\n    targetPath: string;\n    cipher: string;\n    integrityCheck: { ok: boolean; rows: ReadonlyArray<string> };\n    swap?: { originalRenamedTo: string };\n  }>;\n  rekeyDatabase(args: { path: string; oldPassphrase: string; newPassphrase: string }): Promise<{\n    path: string;\n    cipher: string;\n    integrityCheck: { ok: boolean; rows: ReadonlyArray<string> };\n  }>;\n}\n\n/** @internal */\nasync function loadEncryptedSubpack(): Promise<EncryptedSubpack | null> {\n  try {\n    // Computed module name keeps TypeScript's resolution off the\n    // build-time graph so the CLI typechecks without the optional\n    // package installed.\n    const moduleName = '@graphorin/store-sqlite-encrypted';\n    const mod = (await import(/* @vite-ignore */ moduleName)) as Partial<EncryptedSubpack>;\n    if (typeof mod?.encryptDatabase === 'function' && typeof mod?.rekeyDatabase === 'function') {\n      return mod as EncryptedSubpack;\n    }\n    return null;\n  } catch {\n    return null;\n  }\n}\n\n/** @internal */\nasync function resolvePassphraseRef(ref: string): Promise<SecretValue> {\n  try {\n    return await resolveSecret(ref);\n  } catch (err) {\n    throw new Error(\n      `[graphorin/cli] failed to resolve storage passphrase '${ref}': ${(err as Error).message}`,\n      { cause: err },\n    );\n  }\n}\n\nasync function statSafely(\n  path: string,\n): Promise<{ readonly exists: boolean; readonly size?: number }> {\n  try {\n    const s = await stat(path);\n    return { exists: true, size: s.size };\n  } catch {\n    return { exists: false };\n  }\n}\n\n// IP-20: resolve a relative storage path against the CWD — the SAME rule the\n// server (`createServer` → `createSqliteStore`) and `openStoreContext` use — so\n// `graphorin storage status / encrypt` from any directory reports the same\n// database the server and the other CLI commands (`memory`, …) open. Resolving\n// against the config-file dir made `storage status` the lone outlier: from a\n// foreign CWD it inspected a different `data.db` than everything else.\nfunction resolveStoragePath(target: string): string {\n  return isAbsolute(target) ? target : resolve(target);\n}\n\nfunction deriveAuditPath(storagePath: string): string {\n  const idx = storagePath.lastIndexOf('/');\n  if (idx < 0) return 'audit.db';\n  return `${storagePath.slice(0, idx)}/audit.db`;\n}\n\nfunction formatSize(bytes: number | undefined): string {\n  if (bytes === undefined) return 'missing';\n  if (bytes < 1024) return `${bytes} B`;\n  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;\n  return `${(bytes / (1024 * 1024)).toFixed(2)} MiB`;\n}\n\nfunction marker(ok: boolean): string {\n  return ok ? statusMarker('ok') : statusMarker('warn');\n}\n\nfunction failUnsupported(options: CommonOutputOptions, message: string, hint: string): never {\n  const print = options.print ?? defaultPrintSink;\n  print(brand(message));\n  print(brand(`hint: ${hint}`));\n  process.exit(EXIT_CODES.UNSUPPORTED);\n  // `process.exit` returns `never` at runtime, but the type system\n  // narrows the return so explicit callers do not need a cast.\n  /* c8 ignore next */\n  throw new Error('unreachable');\n}\n"],"mappings":"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"}

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,21 @@
+import { CommonOutputOptions } from "../internal/output.js";
+
+//#region src/commands/telemetry.d.ts
+
+/** @stable */
+interface TelemetryStatusResult {
+  readonly enabled: false;
+  readonly policy: 'zero-default';
+  readonly reference: string;
+}
+/** @stable */
+declare function runTelemetryStatus(options?: CommonOutputOptions): TelemetryStatusResult;
+/** @stable */
+declare function runTelemetryEnable(options?: CommonOutputOptions): TelemetryStatusResult;
+/** @stable */
+declare function runTelemetryDisable(options?: CommonOutputOptions): TelemetryStatusResult;
+/** @stable */
+declare function runTelemetryInspect(options?: CommonOutputOptions): TelemetryStatusResult;
+//#endregion
+export { TelemetryStatusResult, runTelemetryDisable, runTelemetryEnable, runTelemetryInspect, runTelemetryStatus };
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/commands/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","names":[],"sources":["../../src/commands/telemetry.ts"],"sourcesContent":[],"mappings":";;;;;UAkCiB,qBAAA;;;;;;iBAeD,kBAAA,WAA4B,sBAA2B;;iBAUvD,kBAAA,WAA4B,sBAA2B;;iBAWvD,mBAAA,WAA6B,sBAA2B;;iBASxD,mBAAA,WAA6B,sBAA2B"}

package/dist/commands/telemetry.js

@@ -0,0 +1,75 @@
+import { brand, defaultPrintSink, emitReport, statusMarker } from "../internal/output.js";
+import { EXIT_CODES } from "../internal/exit.js";
+import process from "node:process";
+
+//#region src/commands/telemetry.ts
+/**
+* `graphorin telemetry` — informational stubs.
+*
+* The framework promises **zero default telemetry** (DEC-154 /
+* ADR-041). The Phase 15 surface ships the four subcommands as
+* stubs that explain the policy and point operators at the
+* documentation. Phase v0.2+ will extend the surface with an opt-in
+* collector; today the stubs ensure the surface name-space is
+* reserved + the operator gets a clear answer.
+*
+* Surface (per Phase 15 § Telemetry):
+*
+*  - `graphorin telemetry status`  — always reports `disabled`.
+*  - `graphorin telemetry enable`  — refuses with a documentation
+*    pointer.
+*  - `graphorin telemetry disable` — no-op success.
+*  - `graphorin telemetry inspect` — informational summary of the
+*    promise (no phone home, no version pings, no crash reports).
+*
+* @packageDocumentation
+*/
+const PRIVACY_REF = "SECURITY.md § Privacy & telemetry (DEC-154 / ADR-041)";
+const ZERO_DEFAULT_RESULT = Object.freeze({
+	enabled: false,
+	policy: "zero-default",
+	reference: PRIVACY_REF
+});
+/** @stable */
+function runTelemetryStatus(options = {}) {
+	emitReport(options, ZERO_DEFAULT_RESULT, () => {
+		const print = options.print ?? defaultPrintSink;
+		print(brand(`${statusMarker("info")} telemetry: disabled (policy: zero-default)`));
+		print(brand(`reference: ${PRIVACY_REF}`));
+	});
+	return ZERO_DEFAULT_RESULT;
+}
+/** @stable */
+function runTelemetryEnable(options = {}) {
+	emitReport(options, ZERO_DEFAULT_RESULT, () => {
+		const print = options.print ?? defaultPrintSink;
+		print(brand(`telemetry enable refused — the framework promises zero phone-home (DEC-154).`));
+		print(brand(`an opt-in collector is on the v0.2+ roadmap; see ${PRIVACY_REF}.`));
+	});
+	process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+	return ZERO_DEFAULT_RESULT;
+}
+/** @stable */
+function runTelemetryDisable(options = {}) {
+	emitReport(options, ZERO_DEFAULT_RESULT, () => {
+		(options.print ?? defaultPrintSink)(brand(`telemetry is already disabled (no-op; zero-default policy).`));
+	});
+	return ZERO_DEFAULT_RESULT;
+}
+/** @stable */
+function runTelemetryInspect(options = {}) {
+	emitReport(options, ZERO_DEFAULT_RESULT, () => {
+		const print = options.print ?? defaultPrintSink;
+		print(brand("graphorin telemetry inspect:"));
+		print(`  ${statusMarker("ok")} no phone home`);
+		print(`  ${statusMarker("ok")} no version pings`);
+		print(`  ${statusMarker("ok")} no crash reports`);
+		print(`  ${statusMarker("ok")} no auto-updates`);
+		print(brand(`reference: ${PRIVACY_REF}`));
+	});
+	return ZERO_DEFAULT_RESULT;
+}
+
+//#endregion
+export { runTelemetryDisable, runTelemetryEnable, runTelemetryInspect, runTelemetryStatus };
+//# sourceMappingURL=telemetry.js.map

package/dist/commands/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","names":["ZERO_DEFAULT_RESULT: TelemetryStatusResult"],"sources":["../../src/commands/telemetry.ts"],"sourcesContent":["/**\n * `graphorin telemetry` — informational stubs.\n *\n * The framework promises **zero default telemetry** (DEC-154 /\n * ADR-041). The Phase 15 surface ships the four subcommands as\n * stubs that explain the policy and point operators at the\n * documentation. Phase v0.2+ will extend the surface with an opt-in\n * collector; today the stubs ensure the surface name-space is\n * reserved + the operator gets a clear answer.\n *\n * Surface (per Phase 15 § Telemetry):\n *\n *  - `graphorin telemetry status`  — always reports `disabled`.\n *  - `graphorin telemetry enable`  — refuses with a documentation\n *    pointer.\n *  - `graphorin telemetry disable` — no-op success.\n *  - `graphorin telemetry inspect` — informational summary of the\n *    promise (no phone home, no version pings, no crash reports).\n *\n * @packageDocumentation\n */\n\nimport process from 'node:process';\n\nimport { EXIT_CODES } from '../internal/exit.js';\nimport {\n  brand,\n  type CommonOutputOptions,\n  defaultPrintSink,\n  emitReport,\n  statusMarker,\n} from '../internal/output.js';\n\n/** @stable */\nexport interface TelemetryStatusResult {\n  readonly enabled: false;\n  readonly policy: 'zero-default';\n  readonly reference: string;\n}\n\nconst PRIVACY_REF = 'SECURITY.md § Privacy & telemetry (DEC-154 / ADR-041)';\n\nconst ZERO_DEFAULT_RESULT: TelemetryStatusResult = Object.freeze({\n  enabled: false,\n  policy: 'zero-default',\n  reference: PRIVACY_REF,\n});\n\n/** @stable */\nexport function runTelemetryStatus(options: CommonOutputOptions = {}): TelemetryStatusResult {\n  emitReport(options, ZERO_DEFAULT_RESULT, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand(`${statusMarker('info')} telemetry: disabled (policy: zero-default)`));\n    print(brand(`reference: ${PRIVACY_REF}`));\n  });\n  return ZERO_DEFAULT_RESULT;\n}\n\n/** @stable */\nexport function runTelemetryEnable(options: CommonOutputOptions = {}): TelemetryStatusResult {\n  emitReport(options, ZERO_DEFAULT_RESULT, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand(`telemetry enable refused — the framework promises zero phone-home (DEC-154).`));\n    print(brand(`an opt-in collector is on the v0.2+ roadmap; see ${PRIVACY_REF}.`));\n  });\n  process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;\n  return ZERO_DEFAULT_RESULT;\n}\n\n/** @stable */\nexport function runTelemetryDisable(options: CommonOutputOptions = {}): TelemetryStatusResult {\n  emitReport(options, ZERO_DEFAULT_RESULT, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand(`telemetry is already disabled (no-op; zero-default policy).`));\n  });\n  return ZERO_DEFAULT_RESULT;\n}\n\n/** @stable */\nexport function runTelemetryInspect(options: CommonOutputOptions = {}): TelemetryStatusResult {\n  emitReport(options, ZERO_DEFAULT_RESULT, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand('graphorin telemetry inspect:'));\n    print(`  ${statusMarker('ok')} no phone home`);\n    print(`  ${statusMarker('ok')} no version pings`);\n    print(`  ${statusMarker('ok')} no crash reports`);\n    print(`  ${statusMarker('ok')} no auto-updates`);\n    print(brand(`reference: ${PRIVACY_REF}`));\n  });\n  return ZERO_DEFAULT_RESULT;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAM,cAAc;AAEpB,MAAMA,sBAA6C,OAAO,OAAO;CAC/D,SAAS;CACT,QAAQ;CACR,WAAW;CACZ,CAAC;;AAGF,SAAgB,mBAAmB,UAA+B,EAAE,EAAyB;AAC3F,YAAW,SAAS,2BAA2B;EAC7C,MAAM,QAAQ,QAAQ,SAAS;AAC/B,QAAM,MAAM,GAAG,aAAa,OAAO,CAAC,6CAA6C,CAAC;AAClF,QAAM,MAAM,cAAc,cAAc,CAAC;GACzC;AACF,QAAO;;;AAIT,SAAgB,mBAAmB,UAA+B,EAAE,EAAyB;AAC3F,YAAW,SAAS,2BAA2B;EAC7C,MAAM,QAAQ,QAAQ,SAAS;AAC/B,QAAM,MAAM,+EAA+E,CAAC;AAC5F,QAAM,MAAM,oDAAoD,YAAY,GAAG,CAAC;GAChF;AACF,SAAQ,WAAW,WAAW;AAC9B,QAAO;;;AAIT,SAAgB,oBAAoB,UAA+B,EAAE,EAAyB;AAC5F,YAAW,SAAS,2BAA2B;AAE7C,GADc,QAAQ,SAAS,kBACzB,MAAM,8DAA8D,CAAC;GAC3E;AACF,QAAO;;;AAIT,SAAgB,oBAAoB,UAA+B,EAAE,EAAyB;AAC5F,YAAW,SAAS,2BAA2B;EAC7C,MAAM,QAAQ,QAAQ,SAAS;AAC/B,QAAM,MAAM,+BAA+B,CAAC;AAC5C,QAAM,KAAK,aAAa,KAAK,CAAC,gBAAgB;AAC9C,QAAM,KAAK,aAAa,KAAK,CAAC,mBAAmB;AACjD,QAAM,KAAK,aAAa,KAAK,CAAC,mBAAmB;AACjD,QAAM,KAAK,aAAa,KAAK,CAAC,kBAAkB;AAChD,QAAM,MAAM,cAAc,cAAc,CAAC;GACzC;AACF,QAAO"}