@aiwayds/dsh-topics-memory 0.6.0

package/lib/store.js

@@ -0,0 +1,489 @@
+/**
+ * Bundle store — reads and writes the local OKF bundle (the Cache).
+ *
+ * All writes go through a serialized queue: one git commit per topic save
+ * (write-through, ADR 0003) plus a regenerated `index.md`. Observations and
+ * the injection log are JSONL sidecars under `meta/`; they are committed on
+ * the flush cadence (sync layer), not per append.
+ *
+ * @module store
+ */
+import { readdir, readFile, writeFile, rename, mkdir, appendFile, access, } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { constants as FsConstants } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import * as okf from "./okf.js";
+import * as gitmod from "./git.js";
+import { actorFor } from "./paths.js";
+export class StoreError extends Error {
+    name = 'StoreError';
+}
+function existsSync(path) {
+    return access(path, FsConstants.F_OK).then(() => true, () => false);
+}
+async function atomicWrite(file, content) {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${randomUUID()}`;
+    await writeFile(tmp, content, 'utf8');
+    await rename(tmp, file);
+}
+export class BundleStore {
+    root;
+    actor;
+    gitDisabled;
+    /** Serializes all write paths; reads are lock-free. */
+    queue = Promise.resolve();
+    constructor(root, opts = {}) {
+        this.root = root;
+        this.actor = opts.actor ?? actorFor();
+        this.gitDisabled = opts.gitDisabled === true;
+    }
+    /** Serialize an async write operation behind the store-wide queue. */
+    enqueue(op) {
+        const run = this.queue.then(op, op);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    topicsDir() {
+        return join(this.root, 'topics');
+    }
+    metaDir() {
+        return join(this.root, 'meta');
+    }
+    topicPath(slug) {
+        return join(this.root, 'topics', `${slug}.md`);
+    }
+    observationsPath() {
+        return join(this.metaDir(), 'observations.jsonl');
+    }
+    injectionsPath() {
+        return join(this.metaDir(), 'injections.jsonl');
+    }
+    conflictsPath() {
+        return join(this.metaDir(), 'conflicts.json');
+    }
+    distillStatePath() {
+        return join(this.metaDir(), 'distill-state.json');
+    }
+    /** Last distill-lane run outcome (diagnostics for /topics status and e2e). */
+    async writeDistillState(state) {
+        await mkdir(this.metaDir(), { recursive: true });
+        await atomicWrite(this.distillStatePath(), `${JSON.stringify(state, null, 2)}\n`);
+    }
+    async readDistillState() {
+        try {
+            return JSON.parse(await readFile(this.distillStatePath(), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Create the directory skeleton, git repo, and initial index (idempotent). */
+    async ensure() {
+        await mkdir(this.topicsDir(), { recursive: true });
+        await mkdir(this.metaDir(), { recursive: true });
+        if (!this.gitDisabled && !(await gitmod.isRepo(this.root))) {
+            await gitmod.initRepo(this.root);
+        }
+        if (!(await existsSync(join(this.root, 'index.md')))) {
+            await this.enqueue(() => this.regenerateIndex());
+        }
+    }
+    /** Repo initialized and not gitDisabled. */
+    async hasGit() {
+        return !this.gitDisabled && gitmod.isRepo(this.root);
+    }
+    async commit(paths, message) {
+        if (this.gitDisabled)
+            return false;
+        if (!(await gitmod.isRepo(this.root)))
+            return false;
+        return gitmod.addAndCommit(this.root, paths, message);
+    }
+    async listTopics() {
+        let files;
+        try {
+            files = await readdir(this.topicsDir());
+        }
+        catch {
+            return [];
+        }
+        const metas = [];
+        for (const f of files) {
+            if (!f.endsWith('.md') || f === 'index.md')
+                continue;
+            try {
+                const raw = await readFile(join(this.topicsDir(), f), 'utf8');
+                const doc = okf.parseTopicDoc(raw);
+                metas.push({
+                    slug: f.slice(0, -3),
+                    title: doc.fm.title,
+                    description: doc.fm.description,
+                    status: doc.fm.status,
+                    tags: doc.fm.tags,
+                    depends: doc.fm.depends,
+                    generatedAt: doc.fm.generated.at,
+                });
+            }
+            catch {
+                // Broken topic files are skipped from rosters; status() surfaces them.
+            }
+        }
+        return metas;
+    }
+    /** Topics broken beyond parsing — surfaced by /topics status, never silently dropped. */
+    async brokenTopics() {
+        let files;
+        try {
+            files = await readdir(this.topicsDir());
+        }
+        catch {
+            return [];
+        }
+        const broken = [];
+        for (const f of files) {
+            if (!f.endsWith('.md') || f === 'index.md')
+                continue;
+            try {
+                okf.parseTopicDoc(await readFile(join(this.topicsDir(), f), 'utf8'));
+            }
+            catch {
+                broken.push(f);
+            }
+        }
+        return broken;
+    }
+    async readTopic(slug) {
+        if (!okf.RESERVED_FILES.has(`${slug}.md`)) {
+            try {
+                return okf.parseTopicDoc(await readFile(this.topicPath(slug), 'utf8'));
+            }
+            catch (e) {
+                if (e instanceof Error && e.name === 'OkfError')
+                    throw e;
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    async exists(slug) {
+        return existsSync(this.topicPath(slug));
+    }
+    /** First free slug: `foo`, then `foo-2`, `foo-3`, … */
+    async uniqueSlug(base) {
+        const clean = okf.slugify(base);
+        if (!(await this.exists(clean)))
+            return clean;
+        for (let i = 2;; i += 1) {
+            const candidate = `${clean}-${i}`;
+            if (!(await this.exists(candidate)))
+                return candidate;
+        }
+    }
+    /**
+     * Write a topic (atomic), regenerate the index, and commit both — one
+     * commit per conclusion change (ADR 0003). `slug` in the doc's depends is
+     * NOT normalized here; callers pass bundle-relative paths.
+     */
+    async saveTopic(input, opts) {
+        return this.enqueue(async () => {
+            const slug = okf.slugify(input.slug);
+            const file = this.topicPath(slug);
+            const created = opts.created ?? !(await existsSync(file));
+            const now = new Date().toISOString();
+            const doc = {
+                fm: { ...input.doc.fm, generated: { by: opts.actor ?? this.actor, at: now } },
+                body: input.doc.body,
+            };
+            const raw = okf.serializeTopicDoc(doc);
+            await atomicWrite(file, raw);
+            await this.regenerateIndex();
+            const committed = await this.commit([`topics/${slug}.md`, 'index.md'], opts.message);
+            return { slug, path: `topics/${slug}.md`, committed, created };
+        });
+    }
+    async regenerateIndex() {
+        const metas = await this.listTopics();
+        const entries = metas.map((m) => ({
+            slug: m.slug,
+            title: m.title,
+            description: m.description,
+            status: m.status,
+            tags: m.tags,
+        }));
+        await atomicWrite(join(this.root, 'index.md'), okf.renderIndex(entries));
+        await atomicWrite(join(this.metaDir(), 'backlinks.json'), `${JSON.stringify(await this.computeBacklinks(), null, 2)}\n`);
+    }
+    /**
+     * Reverse-reference index: slug → who references it and how (`depends`
+     * edges + body links). Regenerated on every topic write (ADR 0003
+     * write-through), so it never drifts from the files.
+     */
+    async computeBacklinks() {
+        const backlinks = {};
+        const push = (target, from, via) => {
+            if (target === from)
+                return;
+            const list = backlinks[target] ?? [];
+            if (!list.some((e) => e.slug === from && e.via === via))
+                list.push({ slug: from, via });
+            backlinks[target] = list;
+        };
+        let files;
+        try {
+            files = await readdir(this.topicsDir());
+        }
+        catch {
+            return {};
+        }
+        for (const f of files) {
+            if (!f.endsWith('.md') || f === 'index.md')
+                continue;
+            const slug = f.slice(0, -3);
+            try {
+                const doc = okf.parseTopicDoc(await readFile(join(this.topicsDir(), f), 'utf8'));
+                for (const dep of okf.dependsSlugs(doc.fm))
+                    push(dep, slug, 'depends');
+                for (const link of okf.bodyLinkSlugs(doc.body))
+                    push(link, slug, 'link');
+            }
+            catch {
+                // broken files contribute no edges
+            }
+        }
+        return backlinks;
+    }
+    /** Read the generated backlinks index (empty map when absent). */
+    async readBacklinks() {
+        try {
+            const raw = await readFile(join(this.metaDir(), 'backlinks.json'), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // absent = no backlinks computed yet
+        }
+        return {};
+    }
+    // ------------------------------------------------------------------
+    // Observations (M2 raw material; tool-written from M1)
+    // ------------------------------------------------------------------
+    async appendObservation(input) {
+        const obs = {
+            id: `obs-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`,
+            at: new Date().toISOString(),
+            kind: input.kind,
+            source: input.source,
+            text: input.text,
+            distilled: false,
+        };
+        if (input.sessionId !== undefined)
+            obs.sessionId = input.sessionId;
+        // Behind the store-wide queue: markDistilled / recordUnconsumed rewrite
+        // the whole JSONL file — an unsynchronized append here could interleave
+        // with a rewrite and lose either the new observation or the rewrite.
+        return this.enqueue(async () => {
+            await mkdir(this.metaDir(), { recursive: true });
+            await appendFile(this.observationsPath(), `${JSON.stringify(obs)}\n`, 'utf8');
+            return obs;
+        });
+    }
+    async allObservations(limit = 500) {
+        let raw;
+        try {
+            raw = await readFile(this.observationsPath(), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                // Tolerate a torn last line (crash mid-append).
+            }
+        }
+        return out.slice(-limit);
+    }
+    async undistilledObservations(limit = 40) {
+        return (await this.allObservations(2000)).filter((o) => !o.distilled).slice(-limit);
+    }
+    async markDistilled(ids, intoSlugs) {
+        return this.enqueue(async () => {
+            const all = await this.allObservations(2000);
+            const idSet = new Set(ids);
+            let changed = 0;
+            for (const o of all) {
+                if (idSet.has(o.id) && !o.distilled) {
+                    o.distilled = true;
+                    o.distilledInto = [...intoSlugs];
+                    changed += 1;
+                }
+            }
+            if (changed > 0) {
+                await atomicWrite(this.observationsPath(), all.map((o) => `${JSON.stringify(o)}\n`).join(''));
+                await this.commit(['meta/observations.jsonl'], `topics(meta): distill ${ids.length} observation(s) into ${intoSlugs.join(', ')}`);
+            }
+            return changed;
+        });
+    }
+    /**
+     * GC policy for the distill lane: an observation fed to the model but left
+     * unconsumed by any op has failed one attempt; after OBSERVATION_MAX_ATTEMPTS
+     * failed attempts it is physically deleted. The user explicitly authorized
+     * deleting raw observations the lane demonstrably cannot process — the
+     * alternative is the same head haunting the backlog forever. Consumed
+     * observations leave the pool via markDistilled and never accrue attempts.
+     */
+    static OBSERVATION_MAX_ATTEMPTS = 3;
+    /**
+     * Post-run GC bookkeeping: increment `attempts` for every observation in
+     * `fedIds` that no op in `consumedIds` accounts for, then delete those that
+     * reached OBSERVATION_MAX_ATTEMPTS. Returns the deletion count (the caller
+     * records it in the distill-state detail). Increments persist with the
+     * usual flush cadence; a deletion commits immediately — destroying data
+     * must be traceable in git.
+     */
+    async recordUnconsumed(fedIds, consumedIds) {
+        return this.enqueue(async () => {
+            const all = await this.allObservations(2000);
+            const fed = new Set(fedIds);
+            const consumed = new Set(consumedIds);
+            let changed = 0;
+            let dropped = 0;
+            const kept = [];
+            for (const o of all) {
+                if (fed.has(o.id) && !consumed.has(o.id) && !o.distilled) {
+                    o.attempts = (o.attempts ?? 0) + 1;
+                    changed += 1;
+                }
+                if (!o.distilled && (o.attempts ?? 0) >= BundleStore.OBSERVATION_MAX_ATTEMPTS) {
+                    dropped += 1;
+                    continue;
+                }
+                kept.push(o);
+            }
+            if (changed > 0 || dropped > 0) {
+                await atomicWrite(this.observationsPath(), kept.map((o) => `${JSON.stringify(o)}\n`).join(''));
+            }
+            if (dropped > 0) {
+                await this.commit(['meta/observations.jsonl'], `topics(meta): gc ${dropped} unprocessable observation(s)`);
+            }
+            return { dropped };
+        });
+    }
+    // ------------------------------------------------------------------
+    // Injection log (ADR 0007) — appended per round, committed on flush
+    // ------------------------------------------------------------------
+    async appendInjectionRecord(record) {
+        await mkdir(this.metaDir(), { recursive: true });
+        await appendFile(this.injectionsPath(), `${JSON.stringify(record)}\n`, 'utf8');
+        await this.compactInjectionsIfNeeded();
+    }
+    async compactInjectionsIfNeeded() {
+        const file = this.injectionsPath();
+        let size = 0;
+        try {
+            size = (await readFile(file, 'utf8')).length;
+        }
+        catch {
+            return;
+        }
+        // ~512KB cap; keep the most recent quarter when exceeded (headroom for
+        // the next debounce window before the next compaction).
+        if (size <= 512 * 1024)
+            return;
+        const lines = (await readFile(file, 'utf8')).split('\n').filter((l) => l.trim() !== '');
+        await atomicWrite(file, lines.slice(-Math.max(1, Math.floor(lines.length / 4))).map((l) => `${l}\n`).join(''));
+    }
+    async readInjectionRecords(limit = 2000) {
+        let raw;
+        try {
+            raw = await readFile(this.injectionsPath(), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                // Torn tail line tolerated.
+            }
+        }
+        return out.slice(-limit);
+    }
+    // ------------------------------------------------------------------
+    // Conflicted topics (ADR 0003) — retrieval demotes these
+    // ------------------------------------------------------------------
+    async getConflicts() {
+        try {
+            const raw = await readFile(this.conflictsPath(), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                return new Set(parsed.filter((x) => typeof x === 'string').map((p) => okf.pathToSlug(p)));
+        }
+        catch {
+            // absent = no conflicts
+        }
+        return new Set();
+    }
+    /** Sync variant for the injection hot path. */
+    getConflictsSync() {
+        try {
+            const raw = readFileSync(this.conflictsPath(), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                return new Set(parsed.filter((x) => typeof x === 'string').map((p) => okf.pathToSlug(p)));
+        }
+        catch {
+            // absent = no conflicts
+        }
+        return new Set();
+    }
+    async setConflicts(paths) {
+        await this.enqueue(async () => {
+            if (paths.length === 0) {
+                await atomicWrite(this.conflictsPath(), '[]\n');
+            }
+            else {
+                await atomicWrite(this.conflictsPath(), `${JSON.stringify([...paths], null, 2)}\n`);
+            }
+            await this.commit(['meta/conflicts.json'], `topics(meta): mark ${paths.length} conflicted topic(s)`);
+        });
+    }
+    // ------------------------------------------------------------------
+    // Roster / status
+    // ------------------------------------------------------------------
+    async status() {
+        const metas = await this.listTopics();
+        const byStatus = { draft: 0, stable: 0, deprecated: 0 };
+        for (const m of metas)
+            byStatus[m.status] += 1;
+        const obs = await this.allObservations(2000);
+        const conflicts = [...(await this.getConflicts())];
+        const head = this.gitDisabled ? undefined : await gitmod.headRev(this.root).catch(() => undefined);
+        return {
+            root: this.root,
+            topicCount: metas.length,
+            byStatus,
+            observationsPending: obs.filter((o) => !o.distilled).length,
+            observationsTotal: obs.length,
+            conflicts,
+            broken: await this.brokenTopics(),
+            git: !this.gitDisabled && (await gitmod.isRepo(this.root)),
+            head,
+        };
+    }
+}

package/lib/sync.d.ts

@@ -0,0 +1,52 @@
+/**
+ * GitHub sync layer (ADR 0002/0003/0008) — active only when the `repo`
+ * setting is non-empty; local-only mode bypasses the whole module.
+ *
+ * Semantics: pull --rebase (autostash) on session start and before each
+ * push; push debounced (config, default 45s) after write-through commits,
+ * hard flush on session end / plugin dispose. A rebase conflict aborts the
+ * rebase and marks the conflicted topics — demoted in retrieval with a
+ * visible warning, resolved by hand (ADR 0003: no automatic smart merging).
+ *
+ * @module sync
+ */
+import type { BundleStore } from './store.ts';
+export declare function remoteUrlFor(repo: string): string;
+export interface SyncConfig {
+    /** `owner/name`; empty string = local-only mode. */
+    repo: string;
+    pushDebounceSeconds: number;
+}
+export type TokenResolver = () => Promise<string | undefined>;
+export type UrlResolver = (repo: string) => string;
+export declare class Sync {
+    private timer;
+    private pending;
+    private inFlight;
+    lastError: string;
+    lastPushAt?: string;
+    lastPullAt?: string;
+    private readonly store;
+    private readonly cfg;
+    private readonly token;
+    private readonly urlFor;
+    constructor(store: BundleStore, cfg: () => SyncConfig, token?: TokenResolver, urlFor?: UrlResolver);
+    get active(): boolean;
+    /** Session start (or `/topics sync pull`): rebase onto remote, mark conflicts. */
+    pull(): Promise<{
+        ok: boolean;
+        conflicted: string[];
+        message: string;
+    }>;
+    /** Called after every write-through commit — schedules the debounced push. */
+    schedulePush(): void;
+    /** Debounce flush, also used for session end and plugin dispose. */
+    flush(): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** Commit the meta sidecars (injection log, observations) — flush cadence. */
+    commitMeta(): Promise<void>;
+    dispose(): void;
+    private safeToken;
+}

package/lib/sync.js

@@ -0,0 +1,154 @@
+/**
+ * GitHub sync layer (ADR 0002/0003/0008) — active only when the `repo`
+ * setting is non-empty; local-only mode bypasses the whole module.
+ *
+ * Semantics: pull --rebase (autostash) on session start and before each
+ * push; push debounced (config, default 45s) after write-through commits,
+ * hard flush on session end / plugin dispose. A rebase conflict aborts the
+ * rebase and marks the conflicted topics — demoted in retrieval with a
+ * visible warning, resolved by hand (ADR 0003: no automatic smart merging).
+ *
+ * @module sync
+ */
+import { spawn } from 'node:child_process';
+import * as gitmod from "./git.js";
+export function remoteUrlFor(repo) {
+    return `https://github.com/${repo}.git`;
+}
+export class Sync {
+    timer;
+    pending = false;
+    inFlight = Promise.resolve();
+    lastError = '';
+    lastPushAt;
+    lastPullAt;
+    store;
+    cfg;
+    token;
+    urlFor;
+    constructor(store, cfg, token = defaultTokenResolver, urlFor = remoteUrlFor) {
+        this.store = store;
+        this.cfg = cfg;
+        this.token = token;
+        this.urlFor = urlFor;
+    }
+    get active() {
+        return this.cfg().repo !== '';
+    }
+    /** Session start (or `/topics sync pull`): rebase onto remote, mark conflicts. */
+    async pull() {
+        if (!this.active)
+            return { ok: true, conflicted: [], message: 'local-only 模式，无同步' };
+        const token = await this.safeToken();
+        await gitmod.setRemote(this.store.root, this.urlFor(this.cfg().repo));
+        if (!(await gitmod.remoteBranchExists(this.store.root, token))) {
+            this.lastPullAt = new Date().toISOString();
+            return { ok: true, conflicted: [], message: '远端还没有分支，跳过拉取' };
+        }
+        const outcome = await gitmod.pullRebase(this.store.root, token);
+        this.lastPullAt = new Date().toISOString();
+        if (outcome.ok) {
+            // A successful rebase clears previous conflict marks.
+            const prior = await this.store.getConflicts();
+            if (prior.size > 0)
+                await this.store.setConflicts([]);
+            return { ok: true, conflicted: [], message: '已与远端同步' };
+        }
+        const conflictedSlugs = outcome.conflicted.map((p) => p.replace(/^topics\//, '').replace(/\.md$/, ''));
+        if (conflictedSlugs.length > 0) {
+            await this.store.setConflicts(outcome.conflicted);
+        }
+        this.lastError = outcome.output.slice(-500);
+        return { ok: false, conflicted: conflictedSlugs, message: `rebase 冲突：${conflictedSlugs.join('、') || '未知路径'}（已标记降权，待手工解决）` };
+    }
+    /** Called after every write-through commit — schedules the debounced push. */
+    schedulePush() {
+        if (!this.active)
+            return;
+        this.pending = true;
+        if (this.timer !== undefined)
+            return;
+        const seconds = Math.max(1, this.cfg().pushDebounceSeconds);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.flush();
+        }, seconds * 1000);
+        // Never hold the process open for a debounced push.
+        this.timer.unref?.();
+    }
+    /** Debounce flush, also used for session end and plugin dispose. */
+    async flush() {
+        if (!this.active)
+            return { ok: true, message: 'local-only 模式，无同步' };
+        this.pending = false;
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        const run = this.inFlight.then(async () => {
+            if (!(await this.store.hasGit()))
+                return { ok: false, message: 'bundle 不是 git 仓库' };
+            const token = await this.safeToken();
+            await gitmod.setRemote(this.store.root, this.urlFor(this.cfg().repo));
+            if (await gitmod.remoteBranchExists(this.store.root, token)) {
+                const pre = await gitmod.pullRebase(this.store.root, token);
+                if (!pre.ok) {
+                    const conflicted = pre.conflicted.map((p) => p.replace(/^topics\//, '').replace(/\.md$/, ''));
+                    if (conflicted.length > 0)
+                        await this.store.setConflicts(pre.conflicted);
+                    this.lastError = pre.output.slice(-500);
+                    return { ok: false, message: `push 前 rebase 失败：${conflicted.join('、') || pre.output.slice(-120)}` };
+                }
+            }
+            const result = await gitmod.push(this.store.root, token);
+            if (result.ok) {
+                this.lastPushAt = new Date().toISOString();
+                this.lastError = '';
+                return { ok: true, message: '已推送到远端' };
+            }
+            this.lastError = result.output.slice(-500);
+            return { ok: false, message: `push 失败：${result.output.slice(-160)}` };
+        });
+        this.inFlight = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Commit the meta sidecars (injection log, observations) — flush cadence. */
+    async commitMeta() {
+        if (!this.active)
+            return;
+        await gitmod.addAndCommit(this.store.root, ['meta'], 'topics(meta): flush injection log / observations').catch(() => undefined);
+    }
+    dispose() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    async safeToken() {
+        try {
+            return await this.token();
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Env first, gh CLI fallback per dsh-vault precedent; login is never our job. */
+async function defaultTokenResolver() {
+    const env = process.env.GITHUB_TOKEN?.trim();
+    if (env !== undefined && env !== '')
+        return env;
+    return ghCliToken();
+}
+/** gh CLI fallback per dsh-vault precedent; login is never this plugin's job. */
+async function ghCliToken() {
+    return new Promise((resolve) => {
+        const child = spawn('gh', ['auth', 'token'], { stdio: ['ignore', 'pipe', 'ignore'], env: process.env });
+        let out = '';
+        child.stdout?.on('data', (d) => {
+            out += d.toString('utf8');
+        });
+        child.on('error', () => resolve(undefined));
+        child.on('close', (code) => resolve(code === 0 ? out.trim() || undefined : undefined));
+    });
+}