@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.100

package/dist/core/notes/notes-paths.js

@@ -0,0 +1,113 @@
+/**
+ * PR F (2026-06-05): Obsidian-style notes — path resolution.
+ *
+ * Three on-disk surfaces, all rooted at `<workspaceRoot>/.pugi/`:
+ *
+ *   1. Session notes  — `.pugi/notes/sessions/<session-id>.md`
+ *      One markdown file per REPL dispatch. Frontmatter (id, persona,
+ *      command, brief, status, files, timing) + body summary.
+ *
+ *   2. File concept notes — `.pugi/notes/files/<slug>.md`
+ *      One markdown file per touched repo file. Append-only history
+ *      of which sessions touched it. Cross-linked via wiki-links from
+ *      session notes (`[[files/snake-html]]`).
+ *
+ *   3. Daily journal — `.pugi/journal/YYYY-MM-DD.md`
+ *      One markdown file per UTC day. Append-only one-paragraph
+ *      entry per dispatch. Provides a chronological "what shipped
+ *      today" view operators read directly in Obsidian or `cat`.
+ *
+ * The on-disk schema is OPEN by design: operators are encouraged to
+ * point their Obsidian vault at `.pugi/notes` and link freely. We
+ * avoid hidden state files (`.json` indexes, `.db` caches) so the
+ * tree stays grep-able and CI-friendly.
+ *
+ * All path helpers are pure — no fs side effects. The writer module
+ * owns `mkdir -p` + atomic write.
+ */
+import { join, basename, resolve, isAbsolute, sep } from 'node:path';
+/**
+ * Resolve the per-workspace notes root. Mirrors the existing
+ * `.pugi/audit/`, `.pugi/sessions/`, `.pugi/runs/` conventions —
+ * a customer who already pins `.pugi/` in `.gitignore` (most do)
+ * automatically picks up notes without touching their VCS hygiene.
+ */
+export function resolveNotesRoot(workspaceRoot) {
+    return join(workspaceRoot, '.pugi', 'notes');
+}
+/**
+ * Resolve the per-workspace daily-journal root.
+ *
+ * Journal lives ALONGSIDE notes/ rather than under it because the
+ * journal is a chronological surface (one entry per day), distinct
+ * from the topical surface (notes by session/file). Keeping them
+ * sibling dirs matches how Obsidian users typically organise
+ * "Daily Notes" plugin output vs concept notes.
+ */
+export function resolveJournalRoot(workspaceRoot) {
+    return join(workspaceRoot, '.pugi', 'journal');
+}
+/**
+ * Resolve the session-note path for a given session id. Returns an
+ * absolute path under the workspace.
+ *
+ * Session ids are already filesystem-safe (the engine adapter mints
+ * them via crypto.randomUUID + slug normalization) so we pass them
+ * through verbatim. If a future caller hands a session id with path
+ * separators we strip them defensively to prevent path traversal
+ * (callers should never do this, but cheap guard).
+ */
+export function resolveSessionNotePath(workspaceRoot, sessionId) {
+    const safe = sessionId.replace(/[\\/]+/g, '-');
+    return join(resolveNotesRoot(workspaceRoot), 'sessions', `${safe}.md`);
+}
+/**
+ * Resolve the file-concept note path for a given repo-relative file
+ * path. The slug is derived in `slug.ts` so the same file always
+ * maps to the same note across sessions.
+ */
+export function resolveFileNotePath(workspaceRoot, fileSlug) {
+    return join(resolveNotesRoot(workspaceRoot), 'files', `${fileSlug}.md`);
+}
+/**
+ * Resolve the daily-journal path for a given UTC date. We use UTC
+ * intentionally so journal files line up across operator timezone
+ * shifts (laptop in SF, desktop in EU, CI in UTC — all converge on
+ * the same `YYYY-MM-DD.md` for a given session).
+ */
+export function resolveJournalPath(workspaceRoot, utcDate) {
+    const y = utcDate.getUTCFullYear();
+    const m = String(utcDate.getUTCMonth() + 1).padStart(2, '0');
+    const d = String(utcDate.getUTCDate()).padStart(2, '0');
+    return join(resolveJournalRoot(workspaceRoot), `${y}-${m}-${d}.md`);
+}
+/**
+ * Resolve a file path to its repo-relative form for slug derivation.
+ * Returns null when the path is outside the workspace (defensive —
+ * the slug derivation cannot produce a meaningful note for an
+ * absolute path outside the tree).
+ *
+ * Symlinks are not followed; we operate on the lexical path. The
+ * audit-trail module uses the same convention (resolve before
+ * hashing) so cross-feature paths stay consistent.
+ */
+export function toWorkspaceRelative(workspaceRoot, filePath) {
+    const absRoot = resolve(workspaceRoot);
+    const abs = isAbsolute(filePath) ? resolve(filePath) : resolve(absRoot, filePath);
+    if (abs === absRoot)
+        return '.';
+    const prefix = absRoot + sep;
+    if (!abs.startsWith(prefix))
+        return null;
+    return abs.slice(prefix.length);
+}
+/**
+ * Strip the basename to a workspace-relative hint useful when the
+ * caller has nothing better. Lets the journal renderer fall back
+ * gracefully on file paths it cannot resolve against the workspace
+ * (e.g. agent emitted an absolute /tmp path for a scratch file).
+ */
+export function fallbackPathHint(filePath) {
+    return basename(filePath);
+}
+//# sourceMappingURL=notes-paths.js.map

package/dist/core/notes/notes-recorder.js

@@ -0,0 +1,140 @@
+/**
+ * PR F (2026-06-05): Notes recorder — orchestrates session/file/daily
+ * markdown writes at dispatch end.
+ *
+ * Called from `native-pugi.ts` immediately after the `dispatch_end`
+ * audit event fires. The recorder:
+ *   1. Renders the per-session note (`writeNoteAtomic`).
+ *   2. Renders the daily-journal entry (`appendNoteLine`).
+ *   3. For each touched file, renders the file-concept note header
+ *      (atomic, only when the file is empty) and appends a history
+ *      line.
+ *
+ * Side effects gated by `enabled` flag from settings + env var
+ * (`PUGI_NOTES_DISABLE=1` overrides). Every call is wrapped in a
+ * try/catch — notes are a convenience surface, not a correctness
+ * guarantee. The audit-trail JSONL remains the authoritative log.
+ */
+import { statSync, readFileSync } from 'node:fs';
+import { resolveSessionNotePath, resolveFileNotePath, resolveJournalPath, toWorkspaceRelative, fallbackPathHint, } from './notes-paths.js';
+import { fileSlugFor } from './slug.js';
+import { writeNoteAtomic, appendNoteLine } from './notes-writer.js';
+import { renderSessionNote, renderFileNoteHeader, renderFileNoteHistoryLine, renderJournalHeader, renderJournalEntry, } from './renderers.js';
+export const PUGI_NOTES_DISABLE_VAR = 'PUGI_NOTES_DISABLE';
+export function isNotesDisabledByEnv(env = process.env) {
+    const raw = env[PUGI_NOTES_DISABLE_VAR]?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+function fileExists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function fileEmptyOrMissing(path) {
+    try {
+        const buf = readFileSync(path, 'utf8');
+        return buf.trim().length === 0;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Compute (slug, relative path) pairs for every touched file. Paths
+ * outside the workspace fall back to a basename-only slug so the
+ * concept note still lands somewhere readable.
+ */
+function deriveFileSlugs(workspaceRoot, filesChanged) {
+    const out = [];
+    for (const f of filesChanged) {
+        const rel = toWorkspaceRelative(workspaceRoot, f) ?? fallbackPathHint(f);
+        const slug = fileSlugFor(rel);
+        if (slug.length > 0) {
+            out.push({ slug, relativePath: rel });
+        }
+    }
+    return out;
+}
+function durationSeconds(startedAt, endedAt) {
+    const s = Date.parse(startedAt);
+    const e = Date.parse(endedAt);
+    if (Number.isNaN(s) || Number.isNaN(e) || e < s)
+        return 0;
+    return Math.round((e - s) / 1000);
+}
+/**
+ * Single entry point — called from `native-pugi.ts` at dispatch end.
+ * Never throws.
+ */
+export function recordSessionNotes(input) {
+    try {
+        if (!input.config.enabled)
+            return;
+        if (isNotesDisabledByEnv(input.env ?? process.env))
+            return;
+        const fileSlugs = deriveFileSlugs(input.workspaceRoot, input.filesChanged);
+        const snap = {
+            sessionId: input.sessionId,
+            command: input.command,
+            persona: input.persona,
+            brief: input.brief,
+            status: input.status,
+            toolCallCount: input.toolCallCount,
+            turnsUsed: input.turnsUsed,
+            tokensUsed: input.tokensUsed,
+            filesChanged: input.filesChanged,
+            fileSlugs,
+            startedAt: input.startedAt,
+            endedAt: input.endedAt,
+            durationSeconds: durationSeconds(input.startedAt, input.endedAt),
+            reason: input.reason,
+        };
+        // (1) Session note — atomic write.
+        writeNoteAtomic(resolveSessionNotePath(input.workspaceRoot, input.sessionId), renderSessionNote(snap));
+        // (2) Daily journal — header on first write per day, then entry.
+        const endedAtDate = new Date(input.endedAt);
+        const journalPath = resolveJournalPath(input.workspaceRoot, endedAtDate);
+        if (!fileExists(journalPath) || fileEmptyOrMissing(journalPath)) {
+            appendNoteLine(journalPath, renderJournalHeader(endedAtDate));
+        }
+        const journalEntry = {
+            sessionId: input.sessionId,
+            endedAt: input.endedAt,
+            command: input.command,
+            persona: input.persona,
+            brief: input.brief,
+            status: input.status,
+            filesChanged: input.filesChanged,
+        };
+        appendNoteLine(journalPath, renderJournalEntry(journalEntry));
+        // (3) File-concept notes — header on first touch, history line
+        // every touch. Both writes are best-effort.
+        for (const f of fileSlugs) {
+            const path = resolveFileNotePath(input.workspaceRoot, f.slug);
+            if (!fileExists(path) || fileEmptyOrMissing(path)) {
+                appendNoteLine(path, renderFileNoteHeader(f.slug, f.relativePath));
+            }
+            const entry = {
+                sessionId: input.sessionId,
+                slug: f.slug,
+                relativePath: f.relativePath,
+                endedAt: input.endedAt,
+                status: input.status,
+                brief: input.brief,
+            };
+            appendNoteLine(path, renderFileNoteHistoryLine(entry));
+        }
+    }
+    catch {
+        // Notes are best-effort. Failure here MUST NOT propagate to the
+        // dispatch — the customer's primary work is already captured in
+        // the audit-trail JSONL and the per-session events mirror.
+    }
+}
+//# sourceMappingURL=notes-recorder.js.map

package/dist/core/notes/notes-writer.js

@@ -0,0 +1,53 @@
+/**
+ * PR F (2026-06-05): Atomic + append-only file writers for notes.
+ *
+ * Two primitives:
+ *   - `writeNoteAtomic`  — full-file replace via tmp + rename.
+ *     Used for session notes (one file per dispatch, complete).
+ *   - `appendNoteLine`   — `O_APPEND` append. Used for daily journal
+ *     and file-concept history sections.
+ *
+ * Both NEVER throw — failure inside the notes layer must NOT break
+ * a customer dispatch. The audit-trail module follows the same
+ * contract (`writeAuditEvent` catches everything). Notes are
+ * convenience surface, not load-bearing.
+ *
+ * `mkdir -p` runs every call (cheap when dir exists). Mode `0o755`
+ * because operators expect to read these in Obsidian without sudo,
+ * unlike audit trails (`0o700`) which carry tenant boundary.
+ */
+import { mkdirSync, writeFileSync, renameSync, appendFileSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+export function writeNoteAtomic(targetPath, content) {
+    try {
+        mkdirSync(dirname(targetPath), { recursive: true, mode: 0o755 });
+        const tmp = `${targetPath}.${randomBytes(6).toString('hex')}.tmp`;
+        try {
+            writeFileSync(tmp, content, { encoding: 'utf8', mode: 0o644 });
+            renameSync(tmp, targetPath);
+        }
+        catch {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                // tmp may not exist (write failed before fd flushed)
+            }
+        }
+    }
+    catch {
+        // Notes are best-effort. Swallow.
+    }
+}
+export function appendNoteLine(targetPath, line) {
+    try {
+        mkdirSync(dirname(targetPath), { recursive: true, mode: 0o755 });
+        const ensureNewline = line.endsWith('\n') ? line : `${line}\n`;
+        appendFileSync(targetPath, ensureNewline, { encoding: 'utf8', mode: 0o644 });
+    }
+    catch {
+        // Notes are best-effort. Swallow.
+    }
+}
+//# sourceMappingURL=notes-writer.js.map

package/dist/core/notes/slug.js

@@ -0,0 +1,105 @@
+/**
+ * PR F (2026-06-05): Path-to-slug normalization for file concept notes.
+ *
+ * A repo file path like `src/components/Header.tsx` becomes the slug
+ * `src-components-header-tsx`, which maps к
+ * `.pugi/notes/files/src-components-header-tsx.md`. The mapping is:
+ *
+ *   - deterministic (same path → same slug across sessions, so the
+ *     append-only history line lands in the same note);
+ *   - filesystem-safe (no path separators that would create subdirs
+ *     in `.pugi/notes/files/`);
+ *   - Obsidian-link-friendly (lowercase + hyphens, no spaces or
+ *     other characters that need escaping in `[[wiki-links]]`);
+ *   - reversible-enough — the original path is also written into the
+ *     note frontmatter (`path: src/components/Header.tsx`) so tooling
+ *     can recover the canonical form without parsing the slug.
+ *
+ * Why one flat `files/` dir instead of mirroring the repo tree under
+ * `.pugi/notes/files/src/components/Header.md`: Obsidian's `[[link]]`
+ * resolver works best when notes live at a single depth. A flat dir
+ * also keeps the wiki-link grammar simple — `[[files/header-tsx]]`
+ * instead of `[[files/src/components/Header.tsx]]` (the latter is
+ * also a legal Obsidian link but harder to grep + harder to rename
+ * file paths без breaking links).
+ */
+/**
+ * Maximum slug length. Empirically the longest file paths в monorepos
+ * are ~120 chars (deep apps/admin-api/src/modules/.../something.ts).
+ * Cap at 200 to leave headroom and keep `.md` filenames reasonable
+ * across filesystems (Windows MAX_PATH = 260 historically, modern
+ * ext4 = 255 на single component).
+ */
+const MAX_SLUG_CHARS = 200;
+/**
+ * Convert a workspace-relative path to a filesystem-safe slug.
+ *
+ * Examples:
+ *   src/App.jsx               → src-app-jsx
+ *   apps/admin-api/main.ts    → apps-admin-api-main-ts
+ *   README.md                 → readme-md
+ *   .pugi/notes/sessions/x.md → pugi-notes-sessions-x-md (defensive)
+ *   docs/2026-06-05-foo.md    → docs-2026-06-05-foo-md
+ *
+ * Edge cases:
+ *   empty / null / undefined  → `'untitled'` fallback (never throws)
+ *   path with unicode         → unicode preserved when filesystem-safe;
+ *                               separators + control chars normalized
+ *   trailing/leading hyphens  → trimmed
+ *   collapsed multi-hyphens   → single `-`
+ */
+export function fileSlugFor(relativePath) {
+    if (typeof relativePath !== 'string' || relativePath.length === 0) {
+        return 'untitled';
+    }
+    let s = relativePath
+        .toLowerCase()
+        // Path separators + dots → hyphen so the slug stays flat.
+        .replace(/[\\/.]+/g, '-')
+        // Strip anything that is not alphanumeric, hyphen, or non-ASCII
+        // letter (allow CJK / Cyrillic for international repos).
+        .replace(/[^\p{L}\p{N}-]+/gu, '-')
+        // Collapse consecutive hyphens.
+        .replace(/-+/g, '-')
+        // Trim hyphens off the ends.
+        .replace(/^-+|-+$/g, '');
+    if (s.length === 0)
+        return 'untitled';
+    if (s.length > MAX_SLUG_CHARS) {
+        s = s.slice(0, MAX_SLUG_CHARS).replace(/-+$/g, '');
+    }
+    return s;
+}
+/**
+ * Convert an arbitrary string (e.g. a brief like "сделай snake.html")
+ * to a concept slug for the wiki-link grammar. Currently the recorder
+ * doesn't mint these (file slugs cover the v1 surface) but keeping
+ * the helper here keeps the slug rules centralized for PR G's
+ * graph-extraction work.
+ *
+ * Returns `null` rather than `'untitled'` when there is nothing to
+ * slug — callers should suppress the link instead of emitting a
+ * placeholder. Different fallback semantics than `fileSlugFor`
+ * because file slugs ALWAYS have a path to lean on, whereas concept
+ * slugs degrade silently when the input is unusable.
+ */
+export function conceptSlugFor(input) {
+    if (typeof input !== 'string')
+        return null;
+    const trimmed = input.trim();
+    if (trimmed.length === 0)
+        return null;
+    let s = trimmed
+        .toLowerCase()
+        .replace(/[\\/.]+/g, '-')
+        .replace(/[^\p{L}\p{N}-]+/gu, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (s.length === 0)
+        return null;
+    if (s.length > MAX_SLUG_CHARS) {
+        s = s.slice(0, MAX_SLUG_CHARS).replace(/-+$/g, '');
+    }
+    return s;
+}
+//# sourceMappingURL=slug.js.map

package/dist/core/onboarding/ensure-initialized.js

@@ -0,0 +1,133 @@
+/**
+ * UX — `ensureInitialized` helper.
+ *
+ * Auto-init pre-flight for every Pugi command. Before this helper landed,
+ * the only entry points that exercised the init flow were:
+ *
+ *  1. The explicit `pugi init` CLI subcommand.
+ *  2. The REPL's `/init` slash (β1a r1).
+ *  3. Engine commands (`pugi code`, `pugi build`, `pugi sync`) which
+ *     called the legacy `ensureInitialized` in `cli.ts` and threw
+ *     `Error('Run pugi init first')` if the operator ran them in a
+ *     directory without `.pugi/`.
+ *
+ * Read-only commands (`pugi explain`, `pugi review`, `pugi plan`,
+ * `pugi smoke`, `pugi chain new`, ...) silently no-op'd the `.pugi/`
+ * mirror inside the engine adapter, which made early dogfooding
+ * confusing — the operator saw a successful command but no session
+ * artifacts on disk and no idea why.
+ *
+ * Auto-init contract (matches CEO directive ):
+ *
+ *  - `.pugi/` already exists → return `{ status: 'already' }` silently.
+ *  - Interactive TTY + no `.pugi/` → prompt
+ *    "No Pugi workspace found here. Initialize? (Y/n)".
+ *    Default Y. On Y: run `scaffoldPugiWorkspace`, return `{ status:
+ *    'initialized' }`. On n: return `{ status: 'declined' }` so the
+ *    caller can bail with a helpful message.
+ *  - Non-interactive (CI / pipe / --json / --no-tty) + no `.pugi/`:
+ *    default behaviour is conservative — return `{ status: 'declined',
+ *    reason: 'non_interactive' }`. The caller decides how to surface
+ *    this (engine commands bail with a clean error; read-only
+ *    commands MAY continue with degraded semantics).
+ *  - `--no-init` flag forces conservative posture even on interactive
+ *    terminals (operator wants to fail fast).
+ *
+ * Session cache: a command pre-flight that already prompted for and
+ * scaffolded `.pugi/` MUST NOT re-prompt for the same workspace in the
+ * same process. The cache key is the absolute workspace root path. The
+ * cache is process-local (Map) — it does not persist across `pugi`
+ * invocations (a second `pugi code` in the same shell starts fresh and
+ * re-checks the filesystem).
+ *
+ * This module is intentionally framework-free: no Ink, no React, no
+ * readline. The prompt reader is injected via the `prompt` callback so
+ * the spec can drive the helper deterministically and the CLI can
+ * forward to its existing stdin-reader (`readSingleChoice` in cli.ts).
+ */
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Process-local cache of workspaces that already passed the pre-flight
+ * gate. Keyed by absolute root path. The cache is intentionally
+ * additive-only — there is no eviction. A long-running REPL session
+ * stays in one workspace and we never want to re-prompt within it.
+ */
+const initialisedCache = new Set();
+/**
+ * Reset the cache. Exported for spec teardown — production callers
+ * never need this.
+ */
+export function resetInitializedCache() {
+    initialisedCache.clear();
+}
+/**
+ * Detect `.pugi/` at `root`. Pure filesystem read; swallows permission
+ * errors (returns false). Exported so the spec can assert the same
+ * detection the helper uses without re-implementing the check.
+ */
+export function hasPugiWorkspace(root) {
+    const path = resolve(root, '.pugi');
+    try {
+        if (!existsSync(path))
+            return false;
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Auto-init pre-flight. Idempotent and process-cache aware — calling
+ * twice in the same process for the same workspace returns `already`
+ * the second time even if the filesystem state changed underneath.
+ *
+ * Implementation notes:
+ *
+ *  - Returns `{ status: 'already' }` when `.pugi/` exists OR the cache
+ *    remembers this workspace. The cache short-circuit means a second
+ *    command in the same process never blocks on the prompt.
+ *  - Interactive + missing → prompt. The default answer (empty input
+ *    OR a leading `y` / `yes`) maps to scaffold. Anything else
+ *    (`n`, `no`, `cancel`, whitespace + non-y) maps to declined.
+ *  - Scaffolder failures propagate to the caller; the helper does
+ *    NOT swallow them because a failed scaffold means the operator's
+ *    command cannot continue anyway. Tests assert this.
+ */
+export async function ensureInitialized(opts) {
+    const root = resolve(opts.cwd ?? process.cwd());
+    if (initialisedCache.has(root)) {
+        return { status: 'already', root };
+    }
+    if (hasPugiWorkspace(root)) {
+        initialisedCache.add(root);
+        return { status: 'already', root };
+    }
+    if (opts.skip) {
+        return { status: 'declined', root, reason: 'disabled' };
+    }
+    if (!opts.interactive) {
+        return { status: 'declined', root, reason: 'non_interactive' };
+    }
+    if (!opts.prompt) {
+        // Defensive — an interactive caller forgot к wire the prompt
+        // reader. Treat the same as non-interactive rather than throwing
+        // so the surrounding command can degrade gracefully.
+        return { status: 'declined', root, reason: 'non_interactive' };
+    }
+    const write = opts.write ?? ((line) => process.stderr.write(line));
+    write(`No Pugi workspace found at ${root}.\n`);
+    const answer = (await opts.prompt('Initialize a new Pugi workspace here? (Y/n) ')).trim().toLowerCase();
+    // Default = yes (empty input OR leading 'y'). Anything else = no.
+    // Mirrors the gh CLI / the upstream prompt convention where the upper-
+    // case option in `(Y/n)` is the default-on-Enter answer.
+    const acceptedShort = answer === '' || answer === 'y' || answer === 'yes';
+    if (!acceptedShort) {
+        write('Initialization declined.\n');
+        return { status: 'declined', root, reason: 'user_declined' };
+    }
+    await opts.scaffold({ cwd: root });
+    initialisedCache.add(root);
+    return { status: 'initialized', root };
+}
+//# sourceMappingURL=ensure-initialized.js.map

package/dist/core/onboarding/marker.js

@@ -0,0 +1,111 @@
+/**
+ * — Onboarding marker file.
+ *
+ * `~/.pugi/.onboarded` is a single, contentless marker. Its existence
+ * tells the bare-invocation hint check that the operator has already
+ * walked the `/onboarding` wizard at least once, so we no longer print
+ * the "Tip: run `pugi onboarding` to configure defaults" line on
+ * cold-start. The wizard re-runs cleanly — idempotency lives in the
+ * wizard itself, not in the marker.
+ *
+ * Why a marker file (and not just `~/.pugi/config.json`'s existence)?
+ *
+ *  - The config file is touched the moment ANY surface writes a
+ *    default — `pugi style terse --persist`, `pugi permissions ask`,
+ *    `pugi config set …`. Using "config exists" as the proxy for
+ *    "operator has onboarded" would silence the first-run hint for
+ *    operators who never saw the wizard.
+ *
+ *  - The marker is explicit: it is written ONLY by the wizard's exit
+ *    step (or `pugi onboarding --mark-only` for the upgrade-path
+ *    where we want to suppress the hint without forcing a re-walk).
+ *
+ *  - Removing the marker (`rm ~/.pugi/.onboarded`) re-arms the hint
+ *    without nuking the operator's accumulated config — useful for
+ *    QA, support flows, and demo-machine resets.
+ *
+ * Path resolution mirrors the L6/L18 convention: `PUGI_HOME` env wins,
+ * else `~/.pugi`. The marker is touched as an empty file (no JSON, no
+ * timestamp payload) — readers MUST treat existence as the only signal
+ * so a future change to mtime semantics does not break us.
+ *
+ * IO contract:
+ *  - `isOnboarded(env)` — pure read; never throws, returns false on
+ *    any fs error so a corrupted home dir cannot hide the hint.
+ *  - `markOnboarded(env)` — best-effort write; creates `<home>/.pugi/`
+ *    if missing, mode 0o600 on the marker so it never lands in a
+ *    world-readable backup.
+ *  - `clearOnboarded(env)` — best-effort delete; absent file is a
+ *    no-op (not an error). Used by `pugi onboarding --reset` and the
+ *    spec teardown.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+/**
+ * Env override for `~/.pugi`. Same convention as L6 / L18 — spec
+ * fixtures point this at a temp dir so a real developer machine never
+ * lands a stray marker.
+ */
+export const PUGI_HOME_ENV = 'PUGI_HOME';
+/**
+ * Marker basename. Hidden (leading dot) so it does not clutter `ls`
+ * inside `~/.pugi/` next to `config.json` / `session.json`.
+ */
+const MARKER_BASENAME = '.onboarded';
+/**
+ * Resolve the absolute path to the onboarding marker. Exported for the
+ * spec; production callers go through `isOnboarded` / `markOnboarded`.
+ */
+export function onboardingMarkerPath(env = process.env) {
+    const home = env[PUGI_HOME_ENV] ?? resolve(homedir(), '.pugi');
+    return resolve(home, MARKER_BASENAME);
+}
+/**
+ * True when the marker exists. Pure read. Defensive: any fs error
+ * (race with deletion, permission flip) degrades to `false` — printing
+ * the hint twice is harmless, silently swallowing the wizard would
+ * surprise the operator.
+ */
+export function isOnboarded(env = process.env) {
+    try {
+        return existsSync(onboardingMarkerPath(env));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Touch the marker. Creates `<home>/.pugi/` if missing. Idempotent —
+ * re-touching an existing marker is a no-op for the consumer (the file
+ * was already there; the hint was already suppressed).
+ *
+ * Best-effort: a write failure is swallowed because the wizard already
+ * completed its real work (mode + style + telemetry were persisted).
+ * The worst case is a redundant hint on the next `pugi` invocation —
+ * preferable to crashing the freshly-completed wizard with a stat EIO.
+ */
+export function markOnboarded(env = process.env) {
+    const path = onboardingMarkerPath(env);
+    try {
+        mkdirSync(resolve(path, '..'), { recursive: true });
+        writeFileSync(path, '', { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        // intentionally swallowed — see header
+    }
+}
+/**
+ * Remove the marker. Used by `pugi onboarding --reset` (and the spec
+ * teardown). Absent file is a no-op; any other fs error is swallowed
+ * so a permission glitch never leaks out of the reset surface.
+ */
+export function clearOnboarded(env = process.env) {
+    try {
+        rmSync(onboardingMarkerPath(env), { force: true });
+    }
+    catch {
+        // intentionally swallowed — see header
+    }
+}
+//# sourceMappingURL=marker.js.map