@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.51

package/dist/tui/welcome-data.js

@@ -0,0 +1,293 @@
+/**
+ * Pure data layer for the `<WelcomeBanner />` component (CEO P0 #2,
+ * 2026-05-29). Lives in its own module so it can be unit-tested without
+ * rendering Ink, and so the banner component itself contains zero IO.
+ *
+ * The banner is the CC-style 2-column boxed greeting that replaces the
+ * α6.14 wave-3 `<ReplSplash />` on the bare REPL boot path. It mirrors
+ * Claude Code's boot layout:
+ *
+ *     ╭────── Pugi v0.1.0-beta.46 ──────╮
+ *     │                                  │ Tips for getting started
+ *     │      Welcome back Yurii!         │ Run /init to create PUGI.md...
+ *     │                                  │ ───────────
+ *     │         ▗ ▗   ▖ ▖                │ What's new
+ *     │           ▘▘ ▝▝                  │ * 0.1.0-beta.26 — Wave 6 RAG ...
+ *     │  Sonnet 4.6 (1M context) · Founder
+ *     │  yuriy.bulah@gmail.com · pugi-io Org
+ *     │  /Volumes/T9/Web/.../TestRepos2  │
+ *     ╰──────────────────────────────────╯
+ *
+ * Data sources, in priority order:
+ *
+ *   - Account email + tenant + plan: JWT principal decoded from the
+ *     active credential. Falls back to anonymous label when no
+ *     credential is on disk (operator boots `pugi` before login).
+ *   - Greeting first-name: best-effort split of the local part of the
+ *     email. Falls back к "operator" when unauthenticated.
+ *   - Model: env override `PUGI_ENGINE_MODEL_CODE`, then the operator's
+ *     workspace settings `defaultModel`, then "Sonnet 4.6 (1M context)"
+ *     as the locked α7 default.
+ *   - Cwd: absolute path of `process.cwd()` — banner left column shows
+ *     the full path so the operator confirms они are в the right repo.
+ *   - What's new: top 3 release-note titles from `apps/pugi-cli/CHANGELOG.md`
+ *     newer than `~/.pugi/.last-seen-version`. Falls back к the top 3
+ *     overall when last-seen marker is missing. Each entry is a one-line
+ *     headline ("0.1.0-beta.26 — Wave 6 RAG consumer middleware") trimmed
+ *     к 60 chars so the right column does not wrap on a 100-col terminal.
+ *
+ * Every resolver swallows its IO error and returns the documented
+ * fallback so a partial environment (missing CHANGELOG, malformed JWT,
+ * unreadable settings) never blocks the banner.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DEFAULT_API_URL, normalizeApiUrl, readCredentialsFile, resolveActiveCredential, } from '../core/credentials.js';
+import { parseChangelog } from '../core/release-notes/parser.js';
+function decodeJwtPayload(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length < 2)
+            return null;
+        const payload = parts[1];
+        if (!payload)
+            return null;
+        const padded = payload
+            .replace(/-/g, '+')
+            .replace(/_/g, '/')
+            .padEnd(payload.length + ((4 - (payload.length % 4)) % 4), '=');
+        const json = Buffer.from(padded, 'base64').toString('utf8');
+        const obj = JSON.parse(json);
+        if (!obj || typeof obj !== 'object')
+            return null;
+        return {
+            ...(typeof obj.sub === 'string' && { sub: obj.sub }),
+            ...(typeof obj.email === 'string' && { email: obj.email }),
+            ...(typeof obj.customerId === 'string' && { customerId: obj.customerId }),
+            ...(typeof obj.plan === 'string' && { plan: obj.plan }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Resolvers                                                          */
+/* ------------------------------------------------------------------ */
+/**
+ * Derive a greeting first-name from an email's local part. The split
+ * is intentionally aggressive: dot-separated, hyphen-separated, and
+ * digit-stripped so `yuriy.bulah@gmail.com` resolves к "Yuriy" instead
+ * of "yuriy.bulah". Title-cases the first segment. Falls back к
+ * "operator" when no email is available.
+ *
+ * Export so the spec can lock the heuristic against edge cases (numeric
+ * local part, plus-tag aliases, single-letter local part).
+ */
+export function deriveGreetingName(email) {
+    if (!email || typeof email !== 'string')
+        return 'operator';
+    const at = email.indexOf('@');
+    if (at <= 0)
+        return 'operator';
+    const local = email.slice(0, at);
+    // Strip plus-tag aliases (`name+tag@host` → `name`).
+    const noTag = local.split('+')[0] ?? local;
+    // First dot / hyphen / underscore segment wins; this is the
+    // colloquial "given name" surface for the vast majority of work
+    // emails ("first.last@..." / "first-last@...").
+    const firstSegment = noTag.split(/[._-]/)[0] ?? noTag;
+    // Strip trailing digits some signup flows append (`yurii2@`) so the
+    // greeting reads as a name, not a username.
+    const stripped = firstSegment.replace(/[0-9]+$/u, '');
+    if (stripped.length === 0)
+        return 'operator';
+    return stripped.charAt(0).toUpperCase() + stripped.slice(1);
+}
+/**
+ * Resolve the model display string. Priority:
+ *
+ *   1. `PUGI_ENGINE_MODEL_CODE` env override (operator-set in shell).
+ *   2. `.pugi/settings.json` → `defaultModel` field (per-workspace).
+ *   3. Locked α7 default `"Sonnet 4.6 (1M context)"`.
+ *
+ * Returns the value verbatim — the banner is responsible for trimming
+ * if the string is too long for the column.
+ */
+export function resolveModelDisplay(env, settingsOverride) {
+    const envModel = env.PUGI_ENGINE_MODEL_CODE;
+    if (typeof envModel === 'string' && envModel.length > 0)
+        return envModel;
+    const settingsModel = settingsOverride?.defaultModel;
+    if (typeof settingsModel === 'string' && settingsModel.length > 0) {
+        return settingsModel;
+    }
+    return 'Sonnet 4.6 (1M context)';
+}
+/**
+ * Locate the bundled CHANGELOG.md. The CLI ships к
+ * `node_modules/@pugi/cli/dist/tui/welcome-data.js` so the changelog
+ * lives at `node_modules/@pugi/cli/CHANGELOG.md` — two directory hops
+ * up from this file. In a local pnpm dev checkout the structure is the
+ * same (`src/tui/` ⇒ `../../CHANGELOG.md`) because tsx re-resolves the
+ * same relative tree.
+ */
+function defaultChangelogPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolvePath(here, '..', '..', 'CHANGELOG.md');
+}
+/**
+ * Read top-3 "what's new" headlines from the CLI CHANGELOG.md. Each
+ * headline is `<version> — <first non-empty section body line>` trimmed
+ * к 60 chars so the right column does not wrap on a 100-col terminal.
+ * Returns an empty array when the file is missing / unparseable.
+ *
+ * The body-line heuristic walks к the first non-empty, non-section-
+ * header line below the version header. For Keep-a-Changelog entries
+ * the second line is usually `### Added` / `### Fixed`; we skip those
+ * headers и land on the first bullet, which is the operator-visible
+ * one-liner ("- L30 `pugi theme` ...").
+ */
+export function readWhatsNew(changelogPath) {
+    const path = changelogPath ?? defaultChangelogPath();
+    try {
+        if (!existsSync(path))
+            return [];
+        const raw = readFileSync(path, 'utf8');
+        if (!raw || raw.length === 0)
+            return [];
+        const sections = parseChangelog(raw);
+        const headlines = [];
+        for (const section of sections) {
+            if (headlines.length >= 3)
+                break;
+            // Skip the "[Unreleased]" / "[Unreleased] - YYYY-MM-DD" section —
+            // the banner is meant к surface SHIPPED notes only. The parser
+            // captures Unreleased identically к а tagged version, so we
+            // filter here.
+            if (/^unreleased$/i.test(section.version))
+                continue;
+            const firstBullet = pickFirstBullet(section.body);
+            if (!firstBullet)
+                continue;
+            const headline = `${section.version} — ${firstBullet}`;
+            headlines.push(truncate(headline, 60));
+        }
+        return headlines;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Pull the first bullet text out of a Keep-a-Changelog section body.
+ * Skips `### <subsection>` headers, blank lines, и non-bullet prose
+ * (release-note footers like "### Notes"). Returns undefined when no
+ * bullet is present.
+ *
+ * Body lines arrive verbatim from the parser; bullets follow the
+ * `- ` / `* ` Markdown convention. We strip the leading bullet glyph
+ * + the first whitespace run so the rendered string is the bullet
+ * content only.
+ */
+function pickFirstBullet(body) {
+    const lines = body.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith('### '))
+            continue;
+        if (trimmed.startsWith('- ') || trimmed.startsWith('* ')) {
+            // Strip leading bullet glyph + ws and collapse internal MD ticks.
+            return trimmed
+                .slice(2)
+                .replace(/`/g, '')
+                .replace(/\*\*/g, '')
+                .trim();
+        }
+    }
+    return undefined;
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    // Reserve 1 char for the ellipsis so we land on EXACTLY `max`
+    // visible chars including the dot. Single Unicode ellipsis would be
+    // narrower but some terminals render it as а full-width glyph in
+    // CJK locales — ASCII three-dot stays predictable.
+    return `${text.slice(0, max - 1).trimEnd()}…`;
+}
+/**
+ * Resolve the active credential and decode the JWT principal. Returns
+ * the email / tenant / plan triple when authenticated, null fields when
+ * anonymous. Encapsulates the credential + JWT IO so the spec can drive
+ * the resolver via an env override.
+ */
+function resolvePrincipal(env, home) {
+    const credential = resolveActiveCredential(env, home);
+    if (!credential) {
+        const file = readCredentialsFile(home);
+        return {
+            apiUrl: normalizeApiUrl(env.PUGI_API_URL ?? file.activeApiUrl ?? DEFAULT_API_URL),
+        };
+    }
+    const principal = decodeJwtPayload(credential.apiKey);
+    return {
+        apiUrl: credential.apiUrl,
+        ...(principal?.email && { email: principal.email }),
+        ...(principal?.customerId && { tenant: principal.customerId }),
+        ...(principal?.plan && { plan: principal.plan }),
+    };
+}
+/**
+ * Best-effort read of `.pugi/settings.json`. Returns null when the file
+ * is missing / unreadable / malformed so the model resolver can fall
+ * back to the env override + locked default.
+ */
+function readSettingsBlob(cwd) {
+    try {
+        const path = resolvePath(cwd, '.pugi', 'settings.json');
+        if (!existsSync(path))
+            return null;
+        const raw = readFileSync(path, 'utf8');
+        if (!raw || raw.length === 0)
+            return null;
+        const obj = JSON.parse(raw);
+        if (typeof obj?.defaultModel === 'string') {
+            return { defaultModel: obj.defaultModel };
+        }
+        return {};
+    }
+    catch {
+        return null;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Entry point                                                        */
+/* ------------------------------------------------------------------ */
+export function collectWelcomeData(input) {
+    const env = input.env ?? process.env;
+    const home = input.home ?? homedir();
+    const cwd = input.cwd ?? process.cwd();
+    const principal = resolvePrincipal(env, home);
+    const settings = input.settingsOverride !== undefined
+        ? input.settingsOverride
+        : readSettingsBlob(cwd);
+    const greetingName = deriveGreetingName(principal.email);
+    const model = resolveModelDisplay(env, settings);
+    const whatsNew = readWhatsNew(input.changelogPath);
+    return {
+        greetingName,
+        ...(principal.email && { email: principal.email }),
+        ...(principal.tenant && { tenant: principal.tenant }),
+        ...(principal.plan && { plan: principal.plan }),
+        model,
+        cwd,
+        cliVersion: input.cliVersion,
+        whatsNew,
+    };
+}
+//# sourceMappingURL=welcome-data.js.map

package/docs/examples/codegraph.mcp.json

@@ -0,0 +1,10 @@
+{
+  "servers": {
+    "codegraph": {
+      "command": "codegraph",
+      "args": ["serve", "--mcp"],
+      "env": {},
+      "trust": "pending"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.51",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -29,8 +29,11 @@
     "bin/run.js",
     "dist/**/*.js",
     "assets/**/*.ansi",
+    "docs/examples/**/*.json",
+    "test/scenarios/**/*.scenario.txt",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
     "node": ">=22.5.0"
@@ -46,13 +49,13 @@
     "ink": "^5.0.1",
     "linkedom": "^0.18.12",
     "react": "^18.3.1",
-    "tar": "^6.2.1",
+    "tar": "^7.5.11",
     "tinyglobby": "^0.2.16",
     "turndown": "^7.2.4",
     "undici": "^8.3.0",
     "zod": "^3.23.0",
-    "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.5"
+    "@pugi/sdk": "0.1.0-beta.51",
+    "@pugi/personas": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -67,9 +70,12 @@
     "build": "pnpm --filter @pugi/personas --filter @pugi/sdk build && tsc -p tsconfig.json && node scripts/make-bin-executable.mjs",
     "dev": "tsx src/index.ts",
     "typecheck": "pnpm --filter @pugi/personas --filter @pugi/sdk build && tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && node --test --import tsx 'test/**/*.spec.ts' 'test/**/*.spec.tsx'",
+    "test": "pnpm run check:version-lockstep && pnpm run build && node --test --import tsx 'test/**/*.spec.ts' 'test/**/*.spec.tsx' 'src/**/*.spec.ts' 'src/**/*.spec.tsx'",
+    "test:integration": "INTEGRATION=1 pnpm run build && node --test --import tsx 'test/**/*.spec.ts' 'test/**/*.spec.tsx' 'src/**/*.spec.ts' 'src/**/*.spec.tsx'",
     "version:cli": "tsx src/index.ts version",
     "doctor": "tsx src/index.ts doctor --json",
-    "pack:smoke": "node scripts/pack-smoke.mjs"
+    "check:version-lockstep": "bash ../../scripts/check-version-lockstep.sh",
+    "pack:smoke": "pnpm run check:version-lockstep && node scripts/pack-smoke.mjs",
+    "release-gate": "node scripts/secret-scanner.mjs"
   }
 }

package/test/scenarios/codegen-create-file.scenario.txt

@@ -0,0 +1,13 @@
+# scenario: codegen-create-file
+# title: Pugi actually writes a file (not just describes it)
+
+# Anti-regression for task #265 — Pugi must call Write, not describe what
+# it would write. The headless stub responder parses
+# "create FILE with content 'TEXT'" and runs the real fs write so the
+# scenario validates the wiring end-to-end. When Phase 2 lands the live
+# engine path the same scenario carries over verbatim.
+
+> "create hello.txt with content 'hello world'"
+EXPECT: tool-call kind=Write file=hello.txt
+EXPECT: persona-turn contains "wrote hello.txt"
+EXPECT_FILE: hello.txt exists with content "hello world"

package/test/scenarios/compact-force.scenario.txt

@@ -0,0 +1,11 @@
+# scenario: compact-force
+# title: /compact --force is acknowledged
+
+# Phase 1: the stub responder echoes the directive verbatim — Phase 2
+# wires the slash command through to the live compaction loop. Until
+# then this scenario protects the contract between scenario authoring
+# and the harness envelope shape.
+
+> "/compact --force"
+EXPECT: persona-turn contains "/compact"
+EXPECT_NOT: persona-turn contains "Mira"

package/test/scenarios/identity.scenario.txt

@@ -0,0 +1,11 @@
+# scenario: identity
+# title: Pugi self-identifies as Pugi (never as Mira)
+
+# CEO directive feedback_live_console_test_every_publish: every published
+# beta must still answer "ты кто?" with the Pugi persona, never the legacy
+# Mira name. This is the single most-asked dialog in CEO dogfood and the
+# regression that has bitten us most often.
+
+> "ты кто?"
+EXPECT: persona-turn contains "Pugi" OR "Пуджи"
+EXPECT_NOT: persona-turn contains "Mira" OR "Мира"

package/test/scenarios/persona-handoff.scenario.txt

@@ -0,0 +1,11 @@
+# scenario: persona-handoff
+# title: Pugi hands off to Hiroshi when the operator asks for dev work
+
+# Phase 1: the headless stub currently echoes input via the Pugi persona
+# (real dispatch routing wires in Phase 2). The scenario is authored
+# against the Phase 2 contract — for now it documents the intent and
+# the harness keeps it as a soft EXPECT so the corpus stays loadable.
+
+> "Hiroshi, please review the authentication module"
+EXPECT: persona-turn contains "Pugi" OR "Hiroshi" OR "Хироси"
+EXPECT_NOT: persona-turn contains "Mira"

package/test/scenarios/walkback.scenario.txt

@@ -0,0 +1,12 @@
+# scenario: walkback
+# title: Esc-Esc walkback / rewind directive recognized
+
+# CEO parity ask (BIG TRACK 8): the operator must be able to walk back
+# the last turn. Phase 1 ships the harness contract — the live walkback
+# wiring lands in BIG TRACK 8. The scenario asserts the stub responder
+# acknowledges the directive verbatim so the contract holds while the
+# real implementation lands behind it.
+
+> "/rewind 1"
+EXPECT: persona-turn contains "/rewind"
+EXPECT_NOT: persona-turn contains "Mira"

package/dist/core/engine/compaction-hook.js

@@ -1,154 +0,0 @@
-/**
- * Engine loop integration point for the six-tier compaction engine.
- *
- * `maybeCompactAfterTool` is the single function the engine loop calls
- * after each tool result has been appended to the transcript. It:
- *
- *   1. Estimates current context-window pressure (transcript bytes
- *      against the model's budget, plus the static blocks).
- *   2. Calls `selectTier` on the snapshot.
- *   3. Runs the tier. Microcompact / cached_microcompact are sync;
- *      reactive_summary / session_memory / full_compaction / reset
- *      are async-shaped (the call returns before commit when run
- *      against a long transcript) but currently run inline — the
- *      engine loop is single-threaded today, so true backgrounding
- *      waits for the SSE consumer refactor in α5.7.
- *   4. Runs invariant checks against the result. On any violation,
- *      emits `compaction.invariant_violated` and returns the
- *      pre-compaction transcript untouched.
- *   5. On success, emits `compaction.completed` with reclaim numbers
- *      and returns the new transcript for the caller to adopt.
- *   6. On no-op, emits `compaction.skipped` and returns the original.
- *
- * Why a separate file (not inlined into `native-pugi.ts`):
- *
- *   Sprint α5.3 (feat/pugi-cli-hooks-lifecycle-m1-gap-c) is in flight
- *   and already modifies session.ts + tool-bridge + permission. Editing
- *   native-pugi.ts in this PR risks a merge conflict against α5.3's
- *   landing PR. Keeping the wiring as an exported helper means the
- *   one-line callsite in native-pugi.ts can be added in a tiny
- *   follow-up after both α5.3 and α5.5 have landed.
- *
- * Expected callsite in `apps/pugi-cli/src/core/engine/native-pugi.ts`,
- * inside `onToolResult`:
- *
- *   ```ts
- *   const compactionOutcome = await maybeCompactAfterTool({
- *     session,
- *     transcript: currentTranscript,
- *     toolOutputs: recentToolOutputs,
- *     contextBudgetUsed: estimatedTokens,
- *     contextBudgetMax: budget.maxTokens,
- *     workspaceRoot: root,
- *     contextStaticHash: {
- *       instructionsHash,
- *       toolSchemaHash,
- *     },
- *   });
- *   if (compactionOutcome.committed) {
- *     currentTranscript = compactionOutcome.newTranscript;
- *   }
- *   ```
- */
-import { runCompaction, selectTier, } from '../context/compaction.js';
-import { checkInvariants } from '../context/invariants.js';
-import { emitCompactionCompleted, emitCompactionInvariantViolated, emitCompactionSkipped, emitCompactionStarted, } from '../context/compaction-events.js';
-/**
- * Engine-loop callback. See file header for the expected callsite shape.
- *
- * Contract:
- *   - Never throws. All errors degrade to `committed: false` with the
- *     original transcript and an event record.
- *   - On `committed: true`, the caller MUST adopt `newTranscript` as
- *     the live working transcript for the next model turn.
- *   - On `committed: false`, the caller MUST keep the input transcript
- *     and try again on the next tool turn (compaction will retry once
- *     pressure stays above threshold).
- */
-export async function maybeCompactAfterTool(input) {
-    const compactionInput = {
-        sessionId: input.session.id,
-        contextBudgetUsed: input.contextBudgetUsed,
-        contextBudgetMax: input.contextBudgetMax,
-        toolOutputs: input.toolOutputs,
-        transcript: input.transcript,
-        workspaceRoot: input.workspaceRoot,
-    };
-    const tier = selectTier(compactionInput);
-    emitCompactionStarted(input.session, tier, {
-        budgetUsed: input.contextBudgetUsed,
-        budgetMax: input.contextBudgetMax,
-    });
-    let result;
-    try {
-        result = await runCompaction(compactionInput, tier);
-    }
-    catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        emitCompactionSkipped(input.session, tier, `compaction crashed: ${reason}`);
-        return {
-            committed: false,
-            tier,
-            newTranscript: input.transcript,
-            bytesReclaimed: 0,
-            newContextSize: byteSize(input.transcript),
-            violations: [],
-            skipped: true,
-            skipReason: `crashed: ${reason}`,
-        };
-    }
-    if (result.skipped) {
-        emitCompactionSkipped(input.session, tier, result.skipReason || 'no work');
-        return {
-            committed: false,
-            tier,
-            newTranscript: input.transcript,
-            bytesReclaimed: 0,
-            newContextSize: byteSize(input.transcript),
-            violations: [],
-            skipped: true,
-            skipReason: result.skipReason,
-        };
-    }
-    // Invariant gate: static-hash-unchanged is enforced by passing the
-    // same hashes in for `before` and `after` — compaction never touches
-    // static blocks, so the hashes are equal by construction. We pass
-    // both so the contract is explicit; if a future tier introduces a
-    // bug that overwrites static state, the check still catches it.
-    const violations = checkInvariants({
-        before: compactionInput,
-        after: result,
-        summaryText: result.summaryText,
-        staticHashBefore: input.contextStaticHash,
-        staticHashAfter: input.contextStaticHash,
-    });
-    if (violations.length > 0) {
-        for (const v of violations)
-            emitCompactionInvariantViolated(input.session, v);
-        return {
-            committed: false,
-            tier,
-            newTranscript: input.transcript,
-            bytesReclaimed: 0,
-            newContextSize: byteSize(input.transcript),
-            violations,
-            skipped: false,
-            skipReason: '',
-        };
-    }
-    emitCompactionCompleted(input.session, tier, result.bytesReclaimed, result.newContextSize, result.artifactsCreated);
-    return {
-        committed: true,
-        tier,
-        newTranscript: result.newTranscript,
-        bytesReclaimed: result.bytesReclaimed,
-        newContextSize: result.newContextSize,
-        violations: [],
-        skipped: false,
-        skipReason: '',
-    };
-}
-function byteSize(transcript) {
-    return transcript.reduce((sum, t) => sum + Buffer.byteLength(t.content, 'utf8'), 0);
-}
-//# sourceMappingURL=compaction-hook.js.map