@ait-co/console-cli 0.1.29 → 0.1.30

package/README.en.md

@@ -160,21 +160,34 @@ Every command accepts `--json`. When set:
 
 ## Telemetry
 
-`aitcc` can collect optional anonymous usage statistics. **Opt-in only by default** — on first run the CLI prompts for consent in a TTY, and silently defaults to deny in CI/pipe environments.
+`aitcc` collects anonymous usage statistics split into two tiers. See the [privacy page](https://docs.aitc.dev/privacy) for details.
 
-Collected: command name, version, platform, random anonymous ID. No personally identifiable information (email, session, user ID, etc.) is ever sent. See the [privacy page](https://docs.aitc.dev/privacy) for details.
+### Tier 0 — anonymous daily ping (on by default, opt-out)
+
+Once per day per machine, a minimal anonymous ping is sent on every invocation. Collected: `{source, version, platform}`. No PII, no `anon_id` — the server derives a daily hash from IP + User-Agent using a rotating salt, and stores nothing else. This is the minimum signal needed to know "is anyone actually using this version?"
+
+Three ways to opt out:
+
+- `AITC_TELEMETRY=off` environment variable — disables all telemetry for this shell session
+- `--no-telemetry` flag — disables for this single invocation only (not permanent)
+- `aitcc telemetry tier0-off` — permanently opts out (persisted to the state file)
+
+### Tier 1 — detailed events (off by default, opt-in)
+
+On first run in a TTY, the CLI prompts for consent. In CI or pipe environments it silently defaults to deny. Collected: command name, version, platform, random persistent anonymous ID (`anon_id`). No personally identifiable information (email, session, user ID, etc.) is ever sent.
 
 ```sh
-aitcc telemetry status   # show current consent state + anon ID
-aitcc telemetry enable   # enable usage statistics
-aitcc telemetry disable  # disable
-aitcc telemetry delete   # request deletion of server-side data + rotate local anon ID
+aitcc telemetry status          # show both tier status + anon ID
+aitcc telemetry status --json   # machine-readable output
+aitcc telemetry enable          # enable Tier 1 events
+aitcc telemetry disable         # disable Tier 1 events
+aitcc telemetry delete          # request deletion of Tier 1 server data + rotate local anon ID
+aitcc telemetry tier0-off       # permanently opt out of Tier 0 daily ping
+aitcc telemetry tier0-on        # re-enable Tier 0 after a previous tier0-off
 ```
 
 State file: `$XDG_CONFIG_HOME/aitcc/telemetry.json` (fallback `~/.config/aitcc/telemetry.json`, mode `0600`).
 
-> **Note**: events will be rejected server-side until the metrics-ingest `source` allowlist is updated to include `console-cli`. The client-side code is ready.
-
 ## Status
 
 `login`, `logout`, `whoami`, and `upgrade` are implemented end-to-end — `login` drives a real browser over CDP and `whoami` reads the live console member API. `deploy`, `logs`, `status` are next. See the [organization landing page](https://aitc.dev/) for the full roadmap.

package/README.md

@@ -160,21 +160,34 @@ aitcc app deploy --bundle ./dist/app.zip --json
 
 ## 텔레메트리
 
-`aitcc`는 선택적 익명 사용 통계를 수집할 수 있습니다. **기본값은 비활성(opt-in)** — 처음 실행 시 TTY 환경에서만 동의를 묻고, CI/파이프 환경에선 자동으로 비활성화됩니다.
+`aitcc`는 두 단계로 분리된 익명 사용 통계를 수집합니다. 자세한 내용은 [privacy 페이지](https://docs.aitc.dev/privacy) 참조.
 
-수집하는 정보: 실행된 명령 이름, 버전, 플랫폼, 임의 익명 ID. 개인 식별 정보(이메일, 세션, 사용자 ID 등)는 절대 전송하지 않습니다. 자세한 내용은 [privacy 페이지](https://docs.aitc.dev/privacy) 참조.
+### Tier 0 — 일별 익명 핑 (기본 ON, opt-out)
+
+매 실행 시 하루 한 번 익명 핑을 보냅니다. 수집 항목: `{source, version, platform}`. 개인 식별 정보 없음. `anon_id`도 없음 — 서버가 일별 salt로 IP+UA 해시를 계산해 저장하며, 그 외 정보는 저장하지 않습니다. "이 버전을 실제로 쓰는 사람이 있는가"를 파악하기 위한 최소 신호입니다.
+
+opt-out 방법 (세 가지):
+
+- `AITC_TELEMETRY=off` 환경 변수 — 이 쉘 세션 전체 비활성
+- `--no-telemetry` 플래그 — 이 invocation만 비활성 (영구 X)
+- `aitcc telemetry tier0-off` — 영구 opt-out (state file에 저장)
+
+### Tier 1 — 세부 이벤트 (기본 OFF, opt-in)
+
+처음 실행 시 TTY 환경에서만 동의를 묻습니다. CI/파이프 환경에선 자동으로 비활성화됩니다. 수집 항목: 실행된 명령 이름, 버전, 플랫폼, 임의 익명 ID (`anon_id`). 개인 식별 정보(이메일, 세션, 사용자 ID 등)는 절대 전송하지 않습니다.
 
 ```sh
-aitcc telemetry status   # 현재 동의 상태 + 익명 ID 확인
-aitcc telemetry enable   # 통계 수집 활성화
-aitcc telemetry disable  # 비활성화
-aitcc telemetry delete   # 서버에 저장된 데이터 삭제 요청 + 로컬 익명 ID 교체
+aitcc telemetry status          # 두 tier 상태 + 익명 ID 확인
+aitcc telemetry status --json   # machine-readable 출력
+aitcc telemetry enable          # Tier 1 활성화
+aitcc telemetry disable         # Tier 1 비활성화
+aitcc telemetry delete          # 서버에 저장된 Tier 1 데이터 삭제 요청 + 로컬 익명 ID 교체
+aitcc telemetry tier0-off       # Tier 0 익명 핑 영구 비활성화
+aitcc telemetry tier0-on        # Tier 0 다시 활성화
 ```
 
 상태 파일: `$XDG_CONFIG_HOME/aitcc/telemetry.json` (fallback `~/.config/aitcc/telemetry.json`, mode `0600`).
 
-> **참고**: metrics-ingest 서버의 `source` allowlist가 `console-cli`를 포함하도록 업데이트되기 전까지는 이벤트가 서버에서 거부될 수 있습니다. 클라이언트 측 코드는 이미 준비돼 있습니다.
-
 ## 진행 상황
 
 `login`, `logout`, `whoami`, `upgrade`는 end-to-end 동작 — `login`은 CDP로 실제 브라우저를 띄우고 `whoami`는 live console member API를 호출합니다. `deploy`, `logs`, `status`가 다음 작업입니다. 전체 로드맵은 [organization landing page](https://aitc.dev/) 참조.

package/dist/cli.mjs

@@ -9199,7 +9199,7 @@ function resolveVersion() {
 		if (typeof injected === "string" && injected.length > 0) return injected;
 	} catch {}
 	try {
-		return "0.1.29";
+		return "0.1.30";
 	} catch {}
 	return "0.0.0-dev";
 }
@@ -9213,7 +9213,7 @@ const VERSION = resolveVersion();
 * Consistent with devtools' localStorage schema names where applicable.
 */
 /** Current policy version. Bump whenever the privacy policy changes. */
-const CURRENT_POLICY_VERSION = "2026-05-12";
+const CURRENT_POLICY_VERSION = "2026-05-18";
 function telemetryFilePath() {
 	return join(configDir(), "telemetry.json");
 }
@@ -9239,7 +9239,9 @@ async function readStateFile() {
 		schemaVersion: 1,
 		consent: obj.consent,
 		policyVersion: obj.policyVersion,
-		...typeof obj.anonId === "string" ? { anonId: obj.anonId } : {}
+		...typeof obj.anonId === "string" ? { anonId: obj.anonId } : {},
+		...typeof obj.tier0LastSent === "string" ? { tier0LastSent: obj.tier0LastSent } : {},
+		...obj.tier0OptOut === true ? { tier0OptOut: true } : {}
 	};
 }
 async function writeStateFile(state) {
@@ -9272,7 +9274,7 @@ async function resolveEffectiveConsent() {
 	const s = await readStateFile();
 	if (!s) return "undecided";
 	if (s.consent === "granted") {
-		if (s.policyVersion !== "2026-05-12") return "undecided";
+		if (s.policyVersion !== "2026-05-18") return "undecided";
 		return "granted";
 	}
 	return s.consent;
@@ -9289,7 +9291,7 @@ async function getOrCreateAnonId() {
 		...s ?? {
 			schemaVersion: 1,
 			consent: "undecided",
-			policyVersion: "2026-05-12"
+			policyVersion: "2026-05-18"
 		},
 		anonId: id
 	});
@@ -9312,6 +9314,45 @@ async function denyConsent() {
 		...s?.anonId ? { anonId: s.anonId } : {}
 	});
 }
+/** Returns true if Tier 0 pings are permanently opted out. */
+async function isTier0OptedOut() {
+	return (await readStateFile())?.tier0OptOut === true;
+}
+/** Permanently opt out of Tier 0 pings (sets tier0OptOut: true). */
+async function setTier0OptOut(optOut) {
+	const current = await readStateFile() ?? {
+		schemaVersion: 1,
+		consent: "undecided",
+		policyVersion: "2026-05-18"
+	};
+	if (optOut) await writeStateFile({
+		...current,
+		tier0OptOut: true
+	});
+	else {
+		const { tier0OptOut: _removed, ...rest } = current;
+		await writeStateFile(rest);
+	}
+}
+/**
+* Returns the ISO date (YYYY-MM-DD) of the last sent Tier 0 ping, or null.
+*/
+async function getTier0LastSent() {
+	return (await readStateFile())?.tier0LastSent ?? null;
+}
+/**
+* Record that a Tier 0 ping was sent today (ISO date marker).
+*/
+async function markTier0Sent(date) {
+	await writeStateFile({
+		...await readStateFile() ?? {
+			schemaVersion: 1,
+			consent: "undecided",
+			policyVersion: "2026-05-18"
+		},
+		tier0LastSent: date
+	});
+}
 /**
 * Delete data: send DELETE /e?anon_id=... to the server (if we have an id),
 * then rotate local anon_id so subsequent events are unlinkable.
@@ -9335,7 +9376,12 @@ async function deleteMyData(endpoint) {
 /**
 * Telemetry send — fire-and-forget with one retry.
 *
-* Rules:
+* Tier 0 rules:
+*   1. No consent check — fires regardless of opt-in state (unless opted out via tier0OptOut).
+*   2. No anon_id — server generates a daily hash.
+*   3. 5 s timeout, no retry. Drops silently on any failure.
+*
+* Tier 1 rules:
 *   1. If consent ≠ "granted" — drop silently.
 *   2. POST event as JSON with 5 s timeout.
 *   3. On network error or non-2xx: retry ONCE after 2 s. On second failure: drop.
@@ -9372,13 +9418,14 @@ function delay(ms) {
 /** Retry delay in ms — injectable for tests. */
 let RETRY_DELAY_MS = 2e3;
 /**
-* Send a telemetry event. Drops silently if consent is not 'granted'.
+* Send a Tier 1 telemetry event. Drops silently if consent is not 'granted'.
 * Returns a Promise but callers should NOT await it — fire-and-forget only.
 */
 async function send(endpoint, event, version, meta) {
 	if (await readConsentState() !== "granted") return;
 	const sanitized = sanitizeMeta(meta);
 	const payload = {
+		tier: 1,
 		source: "console-cli",
 		event,
 		anon_id: await getOrCreateAnonId(),
@@ -9390,15 +9437,45 @@ async function send(endpoint, event, version, meta) {
 	await delay(RETRY_DELAY_MS);
 	await doFetch(endpoint, payload);
 }
+/**
+* Send a Tier 0 anonymous daily ping.
+* - No anon_id (server generates a daily hash from IP+UA).
+* - No retry. 5 s timeout. Fire-and-forget.
+* - Callers should NOT await this.
+*/
+async function sendTier0Ping(endpoint, version) {
+	const payload = {
+		tier: 0,
+		source: "console-cli",
+		version,
+		platform: process.platform
+	};
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), 5e3);
+	try {
+		await fetch(`${endpoint}/e`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: controller.signal
+		});
+	} catch {} finally {
+		clearTimeout(timeoutId);
+	}
+}
 //#endregion
 //#region src/telemetry/index.ts
 /**
 * Telemetry client — internal to @ait-co/console-cli.
 *
-* Usage: import { trackInvocation, trackInstall } from './telemetry/index.js'
+* Usage: import { trackInvocation, trackTier0Ping } from './telemetry/index.js'
+*
+* Tier 0 (opt-out): anonymous daily ping. Fires on every invocation; client-side
+*   daily dedupe via tier0LastSent. Respects AITC_TELEMETRY=off, --no-telemetry,
+*   and permanent tier0OptOut flag.
 *
-* Events are fire-and-forget (non-blocking). Consent is opt-in only.
-* First invocation on a TTY prompts the user; non-TTY (CI) defaults to deny.
+* Tier 1 (opt-in): detailed events. First invocation on a TTY prompts the user;
+*   non-TTY (CI) defaults to deny.
 *
 * Endpoint override for staging: AITCC_TELEMETRY_ENV=staging
 * (or automatically when VERSION contains '-dev').
@@ -9442,6 +9519,37 @@ async function promptConsent() {
 		rl.close();
 	}
 }
+/**
+* Check whether telemetry is globally disabled via environment or CLI flag.
+* Accepts the parsed --no-telemetry flag value from argv.
+*/
+function isTelemetryGloballyDisabled(noTelemetryFlag) {
+	if (noTelemetryFlag) return true;
+	const env = process.env.AITC_TELEMETRY;
+	if (env !== void 0 && env.toLowerCase() === "off") return true;
+	return false;
+}
+/**
+* Send a Tier 0 anonymous daily ping (fire-and-forget).
+*
+* Skips if:
+*   - AITC_TELEMETRY=off or --no-telemetry flag
+*   - tier0OptOut === true in the state file
+*   - already sent today (tier0LastSent === today's ISO date)
+*
+* On success, records today's date in tier0LastSent for client-side daily dedupe.
+* The server also deduplicates server-side via KV, so this is an extra client guard.
+*/
+async function trackTier0Ping(noTelemetryFlag = false) {
+	try {
+		if (isTelemetryGloballyDisabled(noTelemetryFlag)) return;
+		if (await isTier0OptedOut()) return;
+		const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+		if (await getTier0LastSent() === today) return;
+		sendTier0Ping(TELEMETRY_ENDPOINT, VERSION);
+		await markTier0Sent(today);
+	} catch {}
+}
 /** True only on the first invocation after a fresh install. */
 async function isNewInstall() {
 	const markerPath = `${telemetryFilePath()}.install`;
@@ -9455,11 +9563,14 @@ async function isNewInstall() {
 }
 /**
 * Called at CLI entry point with the resolved top-level command name.
-* Handles first-run consent prompt, install detection, and event send.
+* Handles first-run Tier 1 consent prompt, install detection, and Tier 1 event send.
 * Fire-and-forget: do NOT await this.
+*
+* Note: Tier 0 ping is sent separately via trackTier0Ping() before this call.
 */
-async function trackInvocation(command) {
+async function trackInvocation(command, noTelemetryFlag = false) {
 	try {
+		if (isTelemetryGloballyDisabled(noTelemetryFlag)) return;
 		if (isFirstRun()) await promptConsent();
 		if (await resolveEffectiveConsent() !== "granted") return;
 		if (await isNewInstall()) send(TELEMETRY_ENDPOINT, "cli_install", VERSION, {
@@ -9472,13 +9583,13 @@ async function trackInvocation(command) {
 const telemetryCommand = defineCommand({
 	meta: {
 		name: "telemetry",
-		description: "Manage anonymous usage telemetry (opt-in)."
+		description: "Manage anonymous usage telemetry."
 	},
 	subCommands: {
 		status: defineCommand({
 			meta: {
 				name: "status",
-				description: "Show current telemetry consent state and anon_id."
+				description: "Show current telemetry status for both Tier 0 and Tier 1."
 			},
 			args: { json: {
 				type: "boolean",
@@ -9486,24 +9597,37 @@ const telemetryCommand = defineCommand({
 				default: false
 			} },
 			async run({ args }) {
-				const consent = await resolveEffectiveConsent();
-				const anonId = consent === "granted" ? await getOrCreateAnonId() : null;
+				const [tier1Consent, tier0OptOut, tier0LastSent, anonId] = await Promise.all([
+					resolveEffectiveConsent(),
+					isTier0OptedOut(),
+					getTier0LastSent(),
+					resolveEffectiveConsent().then((c) => c === "granted" ? getOrCreateAnonId() : null)
+				]);
 				const filePath = telemetryFilePath();
+				const tier0Status = tier0OptOut ? "off (opted out)" : "on";
+				const tier0Display = tier0LastSent ? `${tier0Status}  (last sent: ${tier0LastSent})` : tier0Status;
 				if (args.json) {
 					process.stdout.write(`${JSON.stringify({
 						ok: true,
-						consent,
-						policyVersion: CURRENT_POLICY_VERSION,
+						tier0: {
+							status: tier0OptOut ? "opted-out" : "on",
+							lastSent: tier0LastSent ?? null
+						},
+						tier1: {
+							consent: tier1Consent,
+							policyVersion: CURRENT_POLICY_VERSION,
+							...anonId ? { anonId } : {}
+						},
 						endpoint: TELEMETRY_ENDPOINT,
-						...anonId ? { anonId } : {},
 						filePath
 					})}\n`);
 					return exitAfterFlush(ExitCode.Ok);
 				}
-				process.stdout.write(`Telemetry: ${consent}\n`);
-				process.stdout.write(`Policy version: ${CURRENT_POLICY_VERSION}\n`);
-				process.stdout.write(`Endpoint: ${TELEMETRY_ENDPOINT}\n`);
-				if (anonId) process.stdout.write(`Anon ID: ${anonId}\n`);
+				process.stdout.write("Telemetry status\n");
+				process.stdout.write(`  Tier 0 (anonymous daily ping): ${tier0Display}\n`);
+				process.stdout.write(`  Tier 1 (opt-in events):        ${tier1Consent}  (policyVersion: ${CURRENT_POLICY_VERSION})\n`);
+				process.stdout.write(`\nEndpoint:   ${TELEMETRY_ENDPOINT}\n`);
+				if (anonId) process.stdout.write(`Anon ID:    ${anonId}\n`);
 				process.stdout.write(`State file: ${filePath}\n`);
 				return exitAfterFlush(ExitCode.Ok);
 			}
@@ -9575,6 +9699,46 @@ const telemetryCommand = defineCommand({
 				else process.stderr.write("Deletion request failed. Please try again or contact the maintainers.\n");
 				return exitAfterFlush(ok || beforeConsent === "undecided" ? ExitCode.Ok : ExitCode.NetworkError);
 			}
+		}),
+		"tier0-off": defineCommand({
+			meta: {
+				name: "tier0-off",
+				description: "Permanently opt out of the Tier 0 anonymous daily ping."
+			},
+			args: { json: {
+				type: "boolean",
+				description: "Emit machine-readable JSON.",
+				default: false
+			} },
+			async run({ args }) {
+				await setTier0OptOut(true);
+				if (args.json) process.stdout.write(`${JSON.stringify({
+					ok: true,
+					tier0: { status: "opted-out" }
+				})}\n`);
+				else process.stdout.write("Tier 0 anonymous ping disabled. No daily pings will be sent.\n");
+				return exitAfterFlush(ExitCode.Ok);
+			}
+		}),
+		"tier0-on": defineCommand({
+			meta: {
+				name: "tier0-on",
+				description: "Re-enable the Tier 0 anonymous daily ping after a previous tier0-off."
+			},
+			args: { json: {
+				type: "boolean",
+				description: "Emit machine-readable JSON.",
+				default: false
+			} },
+			async run({ args }) {
+				await setTier0OptOut(false);
+				if (args.json) process.stdout.write(`${JSON.stringify({
+					ok: true,
+					tier0: { status: "on" }
+				})}\n`);
+				else process.stdout.write("Tier 0 anonymous ping re-enabled.\n");
+				return exitAfterFlush(ExitCode.Ok);
+			}
 		})
 	}
 });
@@ -10864,7 +11028,10 @@ const main = defineCommand({
 	}
 });
 cleanupStaleUpgradeArtifacts().catch(() => {});
-trackInvocation(process.argv.slice(2).find((a) => !a.startsWith("-")) ?? "(none)");
+const _telemetryCmd = process.argv.slice(2).find((a) => !a.startsWith("-")) ?? "(none)";
+const _noTelemetry = process.argv.includes("--no-telemetry");
+trackTier0Ping(_noTelemetry);
+trackInvocation(_telemetryCmd, _noTelemetry);
 runMain(main);
 //#endregion
 export {};