@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/_lib/surface_tiers.ts

@@ -0,0 +1,127 @@
+/**
+ * Surface-tier (core vs lab) resolution for the install split.
+ *
+ * TypeScript twin of `src/scripts/_lib/surface_tiers.py` (ADR-200 — Python→TS
+ * migration). Public API mirrors the Python module exactly (snake_case kept
+ * deliberately — fidelity over TS idiom).
+ *
+ * road-to-install-contract-stability Phase 2. `core` = the lean stable engine
+ * users install; `lab` = experimental / pilot tooling. A core-only install
+ * excludes `lab`-tier artefacts so lab churn cannot destabilise the adoptable
+ * surface.
+ *
+ * Pack tier lives in `src/config/discovery/packs.yml` (`surface_tier: lab`);
+ * the deployed artefacts carry it in frontmatter — commands as `pack:` (scalar),
+ * skills as `packs:` (list). The script-cluster tier registry is
+ * `src/scripts/surface-tiers.yml` (consumed by the boundary guard, not here).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type * as YamlModule from 'yaml';
+
+// Conservative fallback if packs.yml is unreadable: the day-one lab packs.
+const _LAB_FALLBACK: ReadonlySet<string> = new Set(['ai-video', 'ai-image', 'fun']);
+
+/** Pack ids tagged `surface_tier: lab` in packs.yml (+ safe fallback). */
+export function load_lab_pack_ids(repo_root: string): Set<string> {
+    const vocab = path.join(repo_root, 'src', 'config', 'discovery', 'packs.yml');
+    const ids = new Set<string>();
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const YAML = require('yaml') as typeof YamlModule;
+        // version '1.1' matches PyYAML's safe_load.
+        const data = YAML.parse(fs.readFileSync(vocab, 'utf-8'), { version: '1.1' });
+        for (const entry of (data as unknown[]) ?? []) {
+            if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+                const rec = entry as Record<string, unknown>;
+                if (rec['surface_tier'] === 'lab') {
+                    const pid = rec['id'];
+                    if (typeof pid === 'string') {
+                        ids.add(pid);
+                    }
+                }
+            }
+        }
+    } catch {
+        // packs.yml missing / unparseable / no yaml → conservative fallback.
+        return new Set(_LAB_FALLBACK);
+    }
+    return ids.size > 0 ? ids : new Set(_LAB_FALLBACK);
+}
+
+/**
+ * Parse a markdown file's leading frontmatter into its pack set.
+ *
+ * Handles both shapes: `pack: <id>` (commands) and `packs:` followed by
+ * `- <id>` list items (skills). Returns an empty set on any parse failure
+ * or when the file carries no pack tag.
+ */
+export function frontmatter_packs(md_path: string): Set<string> {
+    let text: string;
+    try {
+        text = fs.readFileSync(md_path, 'utf-8');
+    } catch {
+        // OSError / decode error → empty.
+        return new Set();
+    }
+    if (!text.startsWith('---')) {
+        return new Set();
+    }
+    const end = text.indexOf('\n---', 3);
+    const block = end !== -1 ? text.slice(3, end) : text.slice(3);
+
+    const packs = new Set<string>();
+    let in_packs_list = false;
+    for (const raw of block.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        const stripped = line.trim();
+        if (in_packs_list) {
+            if (stripped.startsWith('- ')) {
+                packs.add(_strip_quotes(stripped.slice(2).trim()));
+                continue;
+            }
+            in_packs_list = false;
+        }
+        if (stripped.startsWith('pack:')) {
+            const val = _strip_quotes(stripped.split(':').slice(1).join(':').trim());
+            if (val) {
+                packs.add(val);
+            }
+        } else if (stripped.startsWith('packs:')) {
+            const inline = stripped.split(':').slice(1).join(':').trim();
+            if (inline.startsWith('[') && inline.endsWith(']')) {
+                for (const raw_item of inline.slice(1, -1).split(',')) {
+                    const item = _strip_quotes(raw_item.trim());
+                    if (item) {
+                        packs.add(item);
+                    }
+                }
+            } else {
+                in_packs_list = true;
+            }
+        }
+    }
+    return packs;
+}
+
+/** True when a deployed markdown artefact belongs to a lab-tier pack. */
+export function is_lab_artefact(md_path: string, lab_ids: Set<string>): boolean {
+    for (const p of frontmatter_packs(md_path)) {
+        if (lab_ids.has(p)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/** Mirror of Python `str.strip("'\"")` — strips matching outer quote chars. */
+function _strip_quotes(s: string): string {
+    let out = s;
+    while (out.length > 0 && (out[0] === "'" || out[0] === '"')) {
+        out = out.slice(1);
+    }
+    while (out.length > 0 && (out[out.length - 1] === "'" || out[out.length - 1] === '"')) {
+        out = out.slice(0, -1);
+    }
+    return out;
+}

package/src/scripts/_lib/token_count.ts

@@ -0,0 +1,126 @@
+/**
+ * Real-tokenizer counting for the budget tooling (roadmap 0B.1).
+ *
+ * TypeScript twin of `src/scripts/_lib/token_count.py` (ADR-200 —
+ * Python→TS migration, Phase 2 / Wave 1). Public API mirrors the
+ * Python module exactly (snake_case kept deliberately).
+ *
+ * `char != token`. Every budget in this suite is historically in
+ * characters; this helper adds a token count *alongside* chars so chars
+ * stay the cheap proxy and tokens become the truth where a real
+ * tokenizer is available.
+ *
+ * Design — no silent installs, no mandatory network:
+ *
+ * - **GPT** — the Python original uses `tiktoken` when installed; no
+ *   tokenizer dependency ships with the TS twin, so the documented
+ *   `chars / 4` proxy applies, flagged `exact: false`
+ *   (`TIKTOKEN_AVAILABLE` is always `false` here — matching the
+ *   Python module's behaviour when tiktoken is absent).
+ * - **Claude** — no offline tokenizer; documented `chars / 3.6` proxy
+ *   flagged `exact: false`.
+ *
+ * Both proxies are intentionally conservative ratios drawn from
+ * English-prose + markdown samples; they are estimates, never gates.
+ *
+ * Parity notes: "chars" counts Unicode code points (Python `len(str)`),
+ * not UTF-16 units; rounding is banker's rounding (Python `round()`).
+ */
+
+// Proxy ratios (chars per token) for the no-tokenizer fallback. Tuned for
+// English markdown rule/skill prose; deliberately conservative.
+const _GPT_CHARS_PER_TOKEN = 4.0;
+const _CLAUDE_CHARS_PER_TOKEN = 3.6;
+
+const _TIKTOKEN_ENCODING = "o200k_base"; // GPT-4o / GPT-4.1 family.
+
+// No tiktoken port ships with the TS twin — always the proxy path.
+export const TIKTOKEN_AVAILABLE = false;
+
+/** A single token measurement and whether it is exact or a proxy. */
+export class TokenCount {
+  readonly tokens: number;
+  readonly exact: boolean;
+
+  constructor(tokens: number, exact: boolean) {
+    this.tokens = tokens;
+    this.exact = exact;
+    Object.freeze(this); // dataclass(frozen=True) parity
+  }
+}
+
+/** Count Unicode code points — Python `len(str)` parity. */
+function _len(text: string): number {
+  let count = 0;
+  // for..of iterates code points, so astral chars count once.
+  for (const _ch of text) count += 1;
+  return count;
+}
+
+/** Python `round()` — round half to even (banker's rounding). */
+function _python_round(x: number): number {
+  const floor = Math.floor(x);
+  const diff = x - floor;
+  if (diff > 0.5) return floor + 1;
+  if (diff < 0.5) return floor;
+  return floor % 2 === 0 ? floor : floor + 1;
+}
+
+/** Render a float like Python's f-string (4.0 → "4.0", 3.6 → "3.6"). */
+function _py_float_repr(x: number): string {
+  return Number.isInteger(x) ? `${x}.0` : `${x}`;
+}
+
+/** GPT token count — char proxy (tiktoken unavailable in the TS twin). */
+export function gpt_tokens(text: string): TokenCount {
+  return new TokenCount(_python_round(_len(text) / _GPT_CHARS_PER_TOKEN), false);
+}
+
+/** Claude token count — documented offline proxy (no local tokenizer). */
+export function claude_tokens(text: string): TokenCount {
+  return new TokenCount(
+    _python_round(_len(text) / _CLAUDE_CHARS_PER_TOKEN),
+    false,
+  );
+}
+
+export interface Measure {
+  chars: number;
+  tokens_gpt: number;
+  tokens_gpt_exact: boolean;
+  tokens_claude: number;
+  tokens_claude_exact: boolean;
+}
+
+/**
+ * Return chars + per-model token counts for one text blob.
+ *
+ * Keys: chars, tokens_gpt, tokens_gpt_exact, tokens_claude,
+ * tokens_claude_exact. The `*_exact` booleans tell a report consumer
+ * whether the number is a real tokenizer count or a proxy estimate.
+ */
+export function measure(text: string): Measure {
+  const g = gpt_tokens(text);
+  const c = claude_tokens(text);
+  return {
+    chars: _len(text),
+    tokens_gpt: g.tokens,
+    tokens_gpt_exact: g.exact,
+    tokens_claude: c.tokens,
+    tokens_claude_exact: c.exact,
+  };
+}
+
+/** One-line provenance of how token counts were produced (for reports). */
+export function method_note(): string {
+  if (TIKTOKEN_AVAILABLE) {
+    return (
+      `tokens_gpt: exact (tiktoken ${_TIKTOKEN_ENCODING}); ` +
+      `tokens_claude: proxy (chars/${_py_float_repr(_CLAUDE_CHARS_PER_TOKEN)})`
+    );
+  }
+  return (
+    `tokens_gpt: proxy (chars/${_py_float_repr(_GPT_CHARS_PER_TOKEN)}, tiktoken not installed); ` +
+    `tokens_claude: proxy (chars/${_py_float_repr(_CLAUDE_CHARS_PER_TOKEN)})`
+  );
+}

package/src/scripts/_lib/update_check.ts

@@ -0,0 +1,297 @@
+/**
+ * Daily update-check banner for the `agent-config` dispatcher.
+ *
+ * TypeScript twin of `src/scripts/_lib/update_check.py` (ADR-200,
+ * Phase 2 / Wave 1 batch B). Pure functions: `check_for_update()`
+ * decides whether a banner should be emitted and returns the banner
+ * string (or `null`). The dispatcher prints the returned string to
+ * `stderr` after the subcommand finishes — never delaying the work,
+ * never prompting.
+ *
+ * Design constraints (mirrored from the Python original):
+ *
+ * - Node builtins only (global `fetch` on Node >= 20).
+ * - 1 s hard timeout on the registry call; network failure is silent.
+ * - 24 h cadence gated by `~/.event4u/agent-config/update-check.json`
+ *   (legacy `~/.config/agent-config/update-check.json` is read once as
+ *   a fallback so the cadence is not reset on the first run after the
+ *   namespace migration).
+ * - Suppress in CI, on non-TTY stdout, when `AGENT_CONFIG_NO_UPDATE_CHECK=1`,
+ *   or when `update_check.enabled: false` in settings.
+ * - State file mode is `0600`.
+ *
+ * Port notes (intentional TS adaptations, semantics preserved):
+ * - `fetch_latest_from_npm` / `check_for_update` are async — Node has
+ *   no synchronous HTTP. The transport stays injectable via the
+ *   `fetcher` parameter (same seam the pytest suite uses).
+ */
+import { randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { EnvMap } from './user_global_paths';
+import * as user_global_paths from './user_global_paths';
+
+export const PACKAGE_NAME = '@event4u/agent-config';
+export const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+/** Hard fetch timeout in seconds (mirrors the Python float). */
+export const FETCH_TIMEOUT_S = 1.0;
+/** 24 h cadence window in milliseconds (Python: `timedelta(hours=24)`). */
+export const CHECK_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+export const STATE_FILENAME = 'update-check.json';
+
+/**
+ * Canonical write target. Reads are routed via `_resolve_state_path`
+ * with a read-fallback to the legacy
+ * `~/.config/agent-config/update-check.json` so a fresh install under
+ * the new namespace does not lose the 24 h cadence window established
+ * by a pre-2.4 install.
+ *
+ * NOTE: like the Python module-level constant, this is frozen at
+ * import time (env override read once on module load) — replicated
+ * quirk, not fixed.
+ */
+export const DEFAULT_STATE_PATH = user_global_paths.write_target(STATE_FILENAME);
+
+/** Return the active state path, preferring the new namespace. */
+function _resolve_state_path(): string {
+    const found = user_global_paths.resolve_with_fallback(STATE_FILENAME);
+    if (found !== null) {
+        return found;
+    }
+    return DEFAULT_STATE_PATH;
+}
+
+export type Fetcher = () => string | null | Promise<string | null>;
+
+/**
+ * Return the `latest` dist-tag version, or `null` on any failure.
+ *
+ * Hard 1 s timeout. Any exception (network, JSON, missing key) yields
+ * `null` — the update check is best-effort. `fetch_impl` is the
+ * injectable transport (defaults to the global `fetch`).
+ */
+export async function fetch_latest_from_npm(
+    options: {
+        timeout?: number;
+        url?: string;
+        fetch_impl?: typeof fetch;
+    } = {},
+): Promise<string | null> {
+    const timeout = options.timeout ?? FETCH_TIMEOUT_S;
+    const url = options.url ?? NPM_REGISTRY_URL;
+    const fetch_impl = options.fetch_impl ?? fetch;
+    try {
+        const resp = await fetch_impl(url, {
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': 'agent-config-update-check',
+            },
+            signal: AbortSignal.timeout(timeout * 1000),
+        });
+        const payload: unknown = await resp.json();
+        if (payload !== null && typeof payload === 'object' && !Array.isArray(payload)) {
+            const version = (payload as Record<string, unknown>).version;
+            if (typeof version === 'string' && version.trim()) {
+                return version.trim();
+            }
+        }
+    } catch {
+        return null;
+    }
+    return null;
+}
+
+function _read_state(state_path: string): Record<string, unknown> {
+    try {
+        const raw = fs.readFileSync(state_path, 'utf-8');
+        const data: unknown = JSON.parse(raw);
+        if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+            return data as Record<string, unknown>;
+        }
+    } catch {
+        // Unreadable / corrupt state — treat as empty, same as Python.
+    }
+    return {};
+}
+
+function _write_state(state_path: string, payload: Record<string, unknown>): void {
+    const parent = path.dirname(state_path);
+    fs.mkdirSync(parent, { recursive: true });
+    // mkstemp equivalent: unique sibling temp file, created 0600.
+    const tmp = path.join(parent, `.update-check-${randomBytes(8).toString('hex')}`);
+    try {
+        // json.dump(indent=2, sort_keys=True) equivalent. (Python also
+        // escapes non-ASCII via ensure_ascii=True — flagged divergence;
+        // payload values are version strings + timestamps, ASCII-only.)
+        const sorted: Record<string, unknown> = {};
+        for (const key of Object.keys(payload).sort()) {
+            sorted[key] = payload[key];
+        }
+        fs.writeFileSync(tmp, JSON.stringify(sorted, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        fs.chmodSync(tmp, 0o600);
+        fs.renameSync(tmp, state_path);
+    } catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        } catch {
+            // Best-effort cleanup, mirroring the Python `except OSError: pass`.
+        }
+        throw err;
+    }
+}
+
+function _should_check(state: Record<string, unknown>, now: Date): boolean {
+    const last = state.last_check_utc;
+    if (typeof last !== 'string') {
+        return true;
+    }
+    // Python: datetime.fromisoformat(last.replace("Z", "+00:00")); a
+    // naive timestamp (no offset) is assumed UTC. JS `Date.parse` would
+    // treat offset-less strings as *local* time — normalize to UTC first.
+    let normalized = last.replace(/Z/g, '+00:00');
+    if (!/[+-]\d{2}:?\d{2}$/.test(normalized)) {
+        normalized = `${normalized}+00:00`;
+    }
+    const last_ms = Date.parse(normalized);
+    if (Number.isNaN(last_ms)) {
+        return true;
+    }
+    return now.getTime() - last_ms >= CHECK_WINDOW_MS;
+}
+
+function _format_banner(latest: string, installed: string): string {
+    return (
+        `ℹ️  agent-config ${latest} available (you have ${installed}).\n` +
+        `    Update: npx ${PACKAGE_NAME} update`
+    );
+}
+
+/** Strict integer parse mirroring Python's `int(p)` (else 0). */
+function _int_or_zero(part: string): number {
+    const trimmed = part.trim();
+    if (/^[+-]?\d+$/.test(trimmed)) {
+        return parseInt(trimmed, 10);
+    }
+    return 0;
+}
+
+/**
+ * Best-effort semver comparison — mirrors the Python `_is_newer`
+ * (leading `v`s stripped, pre-release tail dropped, first three
+ * numeric parts compared, non-numeric parts coerced to 0).
+ *
+ * Exported (despite the underscore) because the pytest suite accesses
+ * `uc._is_newer`; the vitest port does the same.
+ */
+export function _is_newer(latest: string, installed: string): boolean {
+    const parse = (v: string): [number, number, number] => {
+        const core = v.replace(/^v+/, '').split('-')[0] ?? '';
+        const parts = core.split('.');
+        const out: number[] = [];
+        for (const p of parts.slice(0, 3)) {
+            out.push(_int_or_zero(p));
+        }
+        while (out.length < 3) {
+            out.push(0);
+        }
+        return [out[0] as number, out[1] as number, out[2] as number];
+    };
+
+    const a = parse(latest);
+    const b = parse(installed);
+    for (let i = 0; i < 3; i += 1) {
+        if ((a[i] as number) > (b[i] as number)) {
+            return true;
+        }
+        if ((a[i] as number) < (b[i] as number)) {
+            return false;
+        }
+    }
+    return false;
+}
+
+/** Format a Date as `%Y-%m-%dT%H:%M:%SZ` (UTC, no milliseconds). */
+function _format_utc(d: Date): string {
+    return d.toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+/**
+ * Decide whether to show an update banner. Pure (modulo state file).
+ *
+ * Returns the banner string or `null`. `null` covers every
+ * suppression branch (CI, non-TTY, opt-out, within 24 h, network
+ * failure, no update available).
+ */
+export async function check_for_update(
+    installed_version: string,
+    options: {
+        now?: Date | null;
+        state_path?: string | null;
+        env?: EnvMap | null;
+        is_tty?: boolean | null;
+        settings_enabled?: boolean;
+        fetcher?: Fetcher;
+    } = {},
+): Promise<string | null> {
+    const env = options.env ?? process.env;
+    if (env.AGENT_CONFIG_NO_UPDATE_CHECK === '1') {
+        return null;
+    }
+    if (env.CI === '1' || env.CI === 'true' || env.GITHUB_ACTIONS === 'true') {
+        return null;
+    }
+    const settings_enabled = options.settings_enabled ?? true;
+    if (!settings_enabled) {
+        return null;
+    }
+    let is_tty = options.is_tty ?? null;
+    if (is_tty === null) {
+        is_tty = Boolean(process.stdout.isTTY);
+    }
+    if (!is_tty) {
+        return null;
+    }
+
+    const now = options.now ?? new Date();
+    // When the caller does not pin a state path, route through the
+    // fallback resolver so a pre-2.4 install's cadence file is still
+    // consulted before we decide to re-check npm.
+    const read_path = options.state_path ?? _resolve_state_path();
+    const write_path = options.state_path ?? DEFAULT_STATE_PATH;
+    const state = _read_state(read_path);
+    if (!_should_check(state, now)) {
+        const latest = state.last_seen_version;
+        if (typeof latest === 'string' && _is_newer(latest, installed_version)) {
+            return _format_banner(latest, installed_version);
+        }
+        return null;
+    }
+
+    const fetcher = options.fetcher ?? (() => fetch_latest_from_npm());
+    const latest = await fetcher();
+    const fallback_seen = Object.prototype.hasOwnProperty.call(state, 'last_seen_version')
+        ? state.last_seen_version
+        : '';
+    const payload: Record<string, unknown> = {
+        last_check_utc: _format_utc(now),
+        // Python: `latest or state.get("last_seen_version", "")`.
+        last_seen_version: latest ? latest : fallback_seen,
+        installed_version,
+    };
+    try {
+        _write_state(write_path, payload);
+    } catch (err) {
+        // Python swallows OSError only; everything else propagates.
+        const code = (err as NodeJS.ErrnoException).code;
+        if (typeof code !== 'string') {
+            throw err;
+        }
+    }
+
+    if (!latest || !_is_newer(latest, installed_version)) {
+        return null;
+    }
+    return _format_banner(latest, installed_version);
+}