pirl-framework-cli 0.0.0-stage → 1.0.0

package/dist/engine/runStore.js

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The layer runs of each target repository, kept in ~/.pirl/sessions/<repo>/ so /resume can continue any of them
+ * after the TUI was closed, the quota ran out or the network dropped. One file per run, named by its key; each holds
+ * the provider session id, never a credential. The newest KEEP runs of a repository are kept.
+ */
+const KEEP = 20;
+const repoKey = (target) => createHash('sha1').update(target).digest('hex').slice(0, 16);
+const dirFor = (home, target) => join(home, 'sessions', repoKey(target));
+/** Before several runs were kept, a repository's last run was a single file; it becomes one entry of the list. */
+const legacyFile = (home, target) => join(home, 'sessions', `${repoKey(target)}.json`);
+const safeName = (key) => key.replace(/[^\w.-]/g, '_');
+export function saveRun(home, target, run) {
+    const dir = dirFor(home, target);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${safeName(run.key)}.json`);
+    writeFileSync(`${file}.tmp`, JSON.stringify({ target, ...run }, null, 2), 'utf8');
+    renameSync(`${file}.tmp`, file);
+    prune(dir);
+}
+function prune(dir) {
+    const files = readdirSync(dir)
+        .filter(name => name.endsWith('.json'))
+        .map(name => ({ name, time: statSync(join(dir, name)).mtimeMs }))
+        .sort((a, b) => b.time - a.time);
+    for (const file of files.slice(KEEP))
+        rmSync(join(dir, file.name), { force: true });
+}
+function migrateLegacy(home, target) {
+    const legacy = legacyFile(home, target);
+    if (!existsSync(legacy))
+        return;
+    try {
+        const data = JSON.parse(readFileSync(legacy, 'utf8'));
+        const dir = dirFor(home, target);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, 'legacy.json'), JSON.stringify({ ...data, key: 'legacy' }, null, 2), 'utf8');
+    }
+    catch { }
+    rmSync(legacy, { force: true });
+}
+/** The saved runs of `target`, newest first. */
+export function listRuns(home, target) {
+    migrateLegacy(home, target);
+    const dir = dirFor(home, target);
+    if (!existsSync(dir))
+        return [];
+    const runs = [];
+    for (const name of readdirSync(dir).filter(file => file.endsWith('.json'))) {
+        try {
+            const data = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+            if (data.target === target && data.kind && data.request)
+                runs.push({ ...data, key: data.key ?? name.replace(/\.json$/, ''), mtime: statSync(join(dir, name)).mtimeMs });
+        }
+        catch { }
+    }
+    return runs
+        .sort((a, b) => (Date.parse(b.savedAt ?? '') || b.mtime) - (Date.parse(a.savedAt ?? '') || a.mtime))
+        .map(({ mtime: _mtime, ...run }) => run);
+}
+export function clearRun(home, target, key) {
+    rmSync(join(dirFor(home, target), `${safeName(key)}.json`), { force: true });
+}
+/** A run /resume can continue: it was stopped, failed, or is waiting for answers, and has a provider session. */
+export const resumable = (run) => !!run && !!run.sessionId && (run.status === 'stopped' || run.status === 'failed' || run.status === 'waiting' || run.status === 'running');

package/dist/engine/types.js

@@ -0,0 +1,3 @@
+export const LAYER_LABELS = { plan: 'Plan', implement: 'Implement', review: 'Review', chat: 'Chat' };
+export const emptyUsage = () => ({ calls: 0, requests: 0, inputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0, outputTokens: 0, costUsd: 0, models: [] });
+export const totalTokens = (usage) => usage.inputTokens + usage.cacheWriteTokens + usage.cacheReadTokens + usage.outputTokens;

package/dist/hub/framework.js

@@ -0,0 +1,13 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where a framework file is stored inside the package; mirrors `storedPath` in scripts/bundle-framework.mjs. */
+export const storedPath = (path) => path.replace(/(^|\/)\.gitignore$/, '$1gitignore.pirl-bundled');
+export function loadBundledFramework(packageRoot) {
+    const dir = join(packageRoot, 'bundled-framework');
+    const manifestPath = join(dir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Thiếu ${manifestPath}. Chạy \`npm run bundle-framework\` trước.`);
+    }
+    return { manifest: JSON.parse(readFileSync(manifestPath, 'utf8')), filesDir: join(dir, 'files') };
+}
+export const frameworkTag = (version) => `fw-${version}`;

package/dist/hub/hub.js

@@ -0,0 +1,125 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { exec as defaultExec, succeeded } from '../core/exec.js';
+import { frameworkTag, storedPath } from './framework.js';
+/**
+ * The Hub is a local Git repository with no remote:
+ * - `upstream` holds the framework versions as shipped (one commit and one `fw-<version>` tag per version);
+ * - `main` is `upstream` plus the user's own improvements, and is the branch the layers run on.
+ * A CLI update never writes here; only `/framework` brings a newer bundled version in (src/hub/update.ts).
+ */
+export const UPSTREAM = 'upstream';
+export const MAIN = 'main';
+/** Git settings for every Hub command: content stored byte for byte, and no signing prompt from the user's config. */
+export const GIT_FLAGS = ['-c', 'core.autocrlf=false', '-c', 'core.safecrlf=false', '-c', 'commit.gpgsign=false', '-c', 'tag.gpgsign=false'];
+/** Baseline commits on `upstream` are written by the tool, not by the user. */
+export const TOOL_AUTHOR = ['-c', 'user.name=PIRL CLI', '-c', 'user.email=pirl-cli@localhost'];
+export class HubError extends Error {
+}
+export async function git(exec, cwd, args, extra = []) {
+    const result = await exec('git', [...GIT_FLAGS, ...extra, ...args], { cwd, timeoutMs: 60_000 });
+    if (!succeeded(result)) {
+        throw new HubError(`git ${args.join(' ')}: ${(result.error ?? result.stderr).trim() || `exit ${result.code}`}`);
+    }
+    return result.stdout;
+}
+async function isPirlHub(exec, path) {
+    if (!existsSync(join(path, '.git')))
+        return false;
+    const result = await exec('git', ['config', '--local', '--get', 'pirl.hub'], { cwd: path, timeoutMs: 10_000 });
+    return succeeded(result) && result.stdout.trim() === 'true';
+}
+/** Creates the Hub from the bundled framework on first use; never touches a directory that is not a PIRL Hub. */
+export async function ensureHub(path, bundle, exec = defaultExec) {
+    if (existsSync(path)) {
+        if (!(await isPirlHub(exec, path))) {
+            if (readdirSync(path).length > 0) {
+                throw new HubError(`${path} đã tồn tại nhưng không phải Hub của PIRL CLI; CLI không thay đổi thư mục này.`);
+            }
+        }
+        else {
+            return { created: false, status: await hubStatus(path, bundle, exec) };
+        }
+    }
+    // Build in a sibling directory and rename at the end, so an interrupted first run leaves no half-made Hub.
+    mkdirSync(dirname(path), { recursive: true });
+    const staging = `${path}.creating-${process.pid}`;
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true });
+    try {
+        await git(exec, staging, ['init', '--quiet']);
+        await git(exec, staging, ['symbolic-ref', 'HEAD', `refs/heads/${UPSTREAM}`]);
+        await git(exec, staging, ['config', 'core.autocrlf', 'false']);
+        for (const file of Object.keys(bundle.manifest.files)) {
+            const to = join(staging, file);
+            mkdirSync(dirname(to), { recursive: true });
+            cpSync(join(bundle.filesDir, storedPath(file)), to);
+        }
+        await git(exec, staging, ['add', '--all']);
+        const tag = frameworkTag(bundle.manifest.version);
+        await git(exec, staging, ['commit', '--quiet', '-m', `Framework ${tag}`], TOOL_AUTHOR);
+        await git(exec, staging, ['tag', tag]);
+        await git(exec, staging, ['branch', MAIN]);
+        await git(exec, staging, ['checkout', '--quiet', MAIN]);
+        // Marked last: a directory carries the marker only once it is a complete Hub.
+        await git(exec, staging, ['config', 'pirl.hub', 'true']);
+        if (existsSync(path))
+            rmSync(path, { recursive: true, force: true }); // only an empty directory reaches here
+        renameSync(staging, path);
+    }
+    catch (error) {
+        rmSync(staging, { recursive: true, force: true });
+        throw error instanceof HubError ? error : new HubError(String(error));
+    }
+    return { created: true, status: await hubStatus(path, bundle, exec) };
+}
+export function parseLsTree(output) {
+    const files = {};
+    for (const entry of output.split('\0')) {
+        const tab = entry.indexOf('\t');
+        if (tab < 0)
+            continue;
+        const [, type, hash] = entry.slice(0, tab).split(' ');
+        if (type === 'blob' && hash)
+            files[entry.slice(tab + 1)] = hash;
+    }
+    return files;
+}
+/** `git status --porcelain -z`: "XY path" entries; a rename or copy is followed by its original path. */
+export function parsePorcelain(output) {
+    const entries = output.split('\0');
+    const paths = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.length < 4)
+            continue;
+        paths.push(entry.slice(3));
+        if (entry[0] === 'R' || entry[0] === 'C')
+            i++;
+    }
+    return paths;
+}
+export function sameFiles(a, b) {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every(key => a[key] === b[key]);
+}
+export async function hubStatus(path, bundle, exec = defaultExec) {
+    // The original version in use is the latest one merged into `main`, not the newest one staged on `upstream`.
+    const tagResult = await exec('git', ['describe', '--tags', '--abbrev=0', '--match', 'fw-*', MAIN], { cwd: path, timeoutMs: 10_000 });
+    const upstreamFiles = parseLsTree(await git(exec, path, ['ls-tree', '-r', '-z', UPSTREAM]));
+    // Update merges are not improvements of the user's.
+    const ahead = Number((await git(exec, path, ['rev-list', '--count', '--no-merges', `${UPSTREAM}..${MAIN}`])).trim());
+    const uncommitted = parsePorcelain(await git(exec, path, ['status', '--porcelain', '-z']));
+    const branchResult = await exec('git', ['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd: path, timeoutMs: 10_000 });
+    // After an undone update, `upstream` already holds the newer version but `main` does not.
+    const merged = succeeded(await exec('git', ['merge-base', '--is-ancestor', UPSTREAM, MAIN], { cwd: path, timeoutMs: 10_000 }));
+    return {
+        path,
+        upstreamTag: succeeded(tagResult) ? tagResult.stdout.trim() : null,
+        localImprovements: Number.isFinite(ahead) ? ahead : 0,
+        uncommitted,
+        updateAvailable: !sameFiles(upstreamFiles, bundle.manifest.files) || !merged,
+        bundledVersion: bundle.manifest.version,
+        branch: succeeded(branchResult) ? branchResult.stdout.trim() : null,
+    };
+}

package/dist/hub/services.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { proposeMerge } from '../engine/agentMerge.js';
+import { discardImprovements } from '../engine/hubData.js';
+import { hubStatus } from './hub.js';
+import * as update from './update.js';
+/** `/framework` on the real Hub (src/hub/update.ts); the agent merge goes through the user's provider. */
+export function frameworkServices(path, bundle, runner, modelOf) {
+    return {
+        status: () => hubStatus(path, bundle),
+        changes: () => update.localChanges(path),
+        diff: file => update.fileDiff(path, file),
+        textDiff: (from, to) => update.textDiff(from, to),
+        history: () => update.improvementHistory(path),
+        restore: file => update.restoreFile(path, file),
+        lastUpdate: () => update.lastUpdate(path),
+        undo: tag => update.undoUpdate(path, tag),
+        commitUncommitted: files => update.commitUncommitted(path, files),
+        discardUncommitted: async (files) => {
+            const result = await discardImprovements(path, files);
+            if (!result.ok)
+                throw new Error(result.error ?? 'Không bỏ được các thay đổi.');
+        },
+        startUpdate: () => update.startUpdate(path, bundle),
+        resolve: (draft, file, choice) => update.resolveConflict(draft.dir, file, choice),
+        readDraft: (draft, file) => {
+            try {
+                return readFileSync(join(draft.dir, file), 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        proposeMerge: (draft, conflict, config) => proposeMerge(runner, draft.dir, conflict, modelOf(config)),
+        finishUpdate: (draft, python) => update.finishUpdate(path, draft, python),
+        abortUpdate: () => update.removeDraft(path),
+    };
+}

package/dist/hub/update.js

@@ -0,0 +1,261 @@
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { exec as defaultExec, succeeded } from '../core/exec.js';
+import { frameworkTag, storedPath } from './framework.js';
+import { GIT_FLAGS, git, HubError, MAIN, parseLsTree, parsePorcelain, sameFiles, TOOL_AUTHOR, UPSTREAM } from './hub.js';
+/**
+ * What `/framework` does to the Hub (proposal section 9). `main` is never left half-updated: an update is merged in a
+ * draft worktree on its own branch, checked with the framework's tests there, and only then fast-forwarded onto
+ * `main`, with a `pre-update/<version>` tag on the old position so it can be undone.
+ */
+export const DRAFT_BRANCH = 'pirl-update';
+const PRE_UPDATE = 'pre-update/';
+/** Where the draft worktree lives: next to the Hub, never inside it. */
+export const draftDir = (hub) => `${hub}-update`;
+const run = (exec, cwd, args, extra = []) => exec('git', [...GIT_FLAGS, ...extra, ...args], { cwd, timeoutMs: 60_000 });
+/** The Hub must be on `main` with nothing uncommitted before anything here rewrites its files. */
+export async function assertClean(hub, exec = defaultExec) {
+    const branch = (await git(exec, hub, ['symbolic-ref', '--quiet', '--short', 'HEAD'])).trim();
+    if (branch !== MAIN)
+        throw new HubError(`Hub đang ở nhánh ${branch}, không phải ${MAIN}.`);
+    const dirty = parsePorcelain(await git(exec, hub, ['status', '--porcelain', '-z']));
+    if (dirty.length > 0)
+        throw new HubError(`Hub có ${dirty.length} file chưa commit: ${dirty.slice(0, 5).join(', ')}. Commit hoặc bỏ chúng trước.`);
+}
+/** Framework files on `main` that differ from the original on `upstream`: the user's local improvements. */
+export async function localChanges(hub, exec = defaultExec) {
+    const names = (await git(exec, hub, ['diff', '--name-status', '-z', '--no-renames', UPSTREAM, MAIN])).split('\0');
+    const stats = (await git(exec, hub, ['diff', '--numstat', '-z', '--no-renames', UPSTREAM, MAIN])).split('\0');
+    const counts = new Map();
+    for (const entry of stats) {
+        const [added, removed, path] = entry.split('\t');
+        if (path)
+            counts.set(path, { added: Number(added) || 0, removed: Number(removed) || 0 });
+    }
+    const changes = [];
+    for (let i = 0; i + 1 < names.length; i += 2) {
+        const code = names[i];
+        const path = names[i + 1];
+        if (!code || !path)
+            continue;
+        changes.push({ path, status: code === 'A' ? 'added' : code === 'D' ? 'deleted' : 'modified', ...(counts.get(path) ?? { added: 0, removed: 0 }) });
+    }
+    return changes;
+}
+/** The unified diff of one file, from the original framework to the Hub's version. */
+export async function fileDiff(hub, path, exec = defaultExec) {
+    return git(exec, hub, ['diff', '--no-color', '--no-renames', UPSTREAM, MAIN, '--', path]);
+}
+/**
+ * Commits on `main` that are not on `upstream`, newest first: improvements, restores and update merges.
+ * With `path`, only the commits that changed that file.
+ */
+export async function improvementHistory(hub, exec = defaultExec, range = `${UPSTREAM}..${MAIN}`, path) {
+    const format = '%H%x1f%cI%x1f%s%x1f%(trailers:key=Pirl-Record,valueonly,separator=%x2c)%x1f%(trailers:key=Pirl-Source,valueonly,separator=%x2c)%x1e';
+    const output = await git(exec, hub, ['log', ...(path ? [] : ['--first-parent']), `--format=${format}`, range, ...(path ? ['--', path] : [])]);
+    return output
+        .split('\x1e')
+        .map(entry => entry.trim())
+        .filter(Boolean)
+        .map(entry => {
+        const [hash = '', date = '', subject = '', record = '', source = ''] = entry.split('\x1f');
+        return { hash, date, subject, record: record.trim() || null, source: source.trim() || null };
+    });
+}
+/** One commit on `main` that puts a file back as the original framework has it (or removes a file the original lacks). */
+export async function restoreFile(hub, path, exec = defaultExec) {
+    await assertClean(hub, exec);
+    const inUpstream = succeeded(await run(exec, hub, ['cat-file', '-e', `${UPSTREAM}:${path}`]));
+    if (inUpstream)
+        await git(exec, hub, ['checkout', UPSTREAM, '--', path]);
+    else
+        await git(exec, hub, ['rm', '--quiet', '--', path]);
+    const message = [`Restore ${path} to the original framework`, '', 'Pirl-Source: restore'].join('\n');
+    await git(exec, hub, ['commit', '--quiet', '-m', message, '--', path], await identity(hub, exec));
+}
+/** The user's Git identity when it is set; otherwise a local one, so a commit never stops on a missing name. */
+async function identity(hub, exec) {
+    const name = await exec('git', ['config', 'user.name'], { cwd: hub, timeoutMs: 10_000 });
+    const email = await exec('git', ['config', 'user.email'], { cwd: hub, timeoutMs: 10_000 });
+    return succeeded(name) && name.stdout.trim() && succeeded(email) && email.stdout.trim() ? [] : ['-c', 'user.name=PIRL CLI user', '-c', 'user.email=pirl-cli@localhost'];
+}
+/** The latest update that can be undone: a `pre-update/*` tag whose commit is still part of `main`. */
+export async function lastUpdate(hub, exec = defaultExec) {
+    const tags = (await git(exec, hub, ['tag', '--list', `${PRE_UPDATE}*`, '--sort=-creatordate'])).split('\n').map(tag => tag.trim()).filter(Boolean);
+    for (const tag of tags) {
+        if (!succeeded(await run(exec, hub, ['merge-base', '--is-ancestor', tag, MAIN])))
+            continue;
+        const commits = await improvementHistory(hub, exec, `${tag}..${MAIN}`);
+        if (commits.length === 0)
+            continue;
+        return { tag, version: tag.slice(PRE_UPDATE.length).replace(/-\d+$/, ''), commits };
+    }
+    return null;
+}
+/** Puts `main` back where it was before the update; every commit made since then goes too, as the user confirmed. */
+export async function undoUpdate(hub, tag, exec = defaultExec) {
+    await assertClean(hub, exec);
+    await git(exec, hub, ['reset', '--hard', '--quiet', tag]);
+    await git(exec, hub, ['tag', '--delete', tag]);
+}
+// ---------- update ----------
+/** Puts the bundled framework on `upstream` as a new commit and tag; nothing changes when it is already there. */
+export async function stageBundle(hub, bundle, exec = defaultExec) {
+    const tag = frameworkTag(bundle.manifest.version);
+    const upstreamTree = await git(exec, hub, ['ls-tree', '-r', '-z', UPSTREAM]);
+    if (sameFiles(parseLsTree(upstreamTree), bundle.manifest.files))
+        return tag;
+    const modes = new Map();
+    for (const entry of upstreamTree.split('\0')) {
+        const tab = entry.indexOf('\t');
+        if (tab > 0)
+            modes.set(entry.slice(tab + 1), entry.slice(0, tab).split(' ')[0]);
+    }
+    // A private index builds the new tree without touching the Hub's index or working tree.
+    const scratch = mkdtempSync(join(tmpdir(), 'pirl-index-'));
+    const env = { ...process.env, GIT_INDEX_FILE: join(scratch, 'index') };
+    try {
+        const lines = [];
+        for (const [path, expected] of Object.entries(bundle.manifest.files)) {
+            const stored = await exec('git', ['hash-object', '-w', '--no-filters', join(bundle.filesDir, storedPath(path))], { cwd: hub, timeoutMs: 30_000 });
+            const hash = stored.stdout.trim();
+            if (!succeeded(stored) || hash !== expected)
+                throw new HubError(`Framework đi kèm CLI bị hỏng ở ${path}: mã băm không khớp manifest.`);
+            lines.push(`${modes.get(path) ?? '100644'} ${hash}\t${path}`);
+        }
+        const index = await exec('git', ['update-index', '--add', '--index-info'], { cwd: hub, env, input: `${lines.join('\n')}\n`, timeoutMs: 60_000 });
+        if (!succeeded(index))
+            throw new HubError(`git update-index: ${index.stderr.trim()}`);
+        const tree = await exec('git', ['write-tree'], { cwd: hub, env, timeoutMs: 30_000 });
+        if (!succeeded(tree))
+            throw new HubError(`git write-tree: ${tree.stderr.trim()}`);
+        const parent = (await git(exec, hub, ['rev-parse', UPSTREAM])).trim();
+        const commit = (await git(exec, hub, ['commit-tree', tree.stdout.trim(), '-p', parent, '-m', `Framework ${tag}`], TOOL_AUTHOR)).trim();
+        await git(exec, hub, ['update-ref', `refs/heads/${UPSTREAM}`, commit, parent]);
+        await git(exec, hub, ['tag', '--force', tag, commit]);
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    return tag;
+}
+/** Removes a draft left by an update that did not finish. */
+export async function removeDraft(hub, exec = defaultExec) {
+    const dir = draftDir(hub);
+    await run(exec, hub, ['worktree', 'remove', '--force', dir]);
+    rmSync(dir, { recursive: true, force: true });
+    await run(exec, hub, ['worktree', 'prune']);
+    await run(exec, hub, ['branch', '-D', DRAFT_BRANCH]);
+}
+const show = async (exec, cwd, spec) => {
+    const result = await run(exec, cwd, ['show', spec]);
+    return succeeded(result) ? result.stdout : null;
+};
+/** Merges the bundled framework into a draft of `main`; conflicts wait in the draft for the user's choices. */
+export async function startUpdate(hub, bundle, exec = defaultExec) {
+    await assertClean(hub, exec);
+    const tag = await stageBundle(hub, bundle, exec);
+    await removeDraft(hub, exec);
+    const dir = draftDir(hub);
+    await git(exec, hub, ['worktree', 'add', '--quiet', '-b', DRAFT_BRANCH, dir, MAIN]);
+    const changed = (await git(exec, hub, ['diff', '--name-only', '--no-renames', `${MAIN}...${UPSTREAM}`])).split('\n').filter(Boolean);
+    const merge = await run(exec, dir, ['merge', '--no-ff', '--no-commit', UPSTREAM], [...TOOL_AUTHOR, '-c', 'merge.conflictStyle=diff3']);
+    const unmerged = (await git(exec, dir, ['diff', '--name-only', '--diff-filter=U'])).split('\n').filter(Boolean);
+    if (!succeeded(merge) && unmerged.length === 0) {
+        await removeDraft(hub, exec);
+        throw new HubError(`git merge: ${(merge.stderr || merge.stdout).trim()}`);
+    }
+    const conflicts = [];
+    for (const path of unmerged) {
+        conflicts.push({
+            path,
+            base: await show(exec, dir, `:1:${path}`),
+            mine: await show(exec, dir, `:2:${path}`),
+            theirs: await show(exec, dir, `:3:${path}`),
+            myCommits: await improvementHistory(hub, exec, `${UPSTREAM}..${MAIN}`, path),
+        });
+    }
+    return { dir, tag, changed, conflicts };
+}
+export const hasConflictMarkers = (text) => /^(<<<<<<<|>>>>>>>|\|\|\|\|\|\|\|)( |$)/m.test(text);
+/** Settles one conflict in the draft: the user's version, the new original, or given content (null removes the file). */
+export async function resolveConflict(dir, path, choice, exec = defaultExec) {
+    if (choice === 'mine' || choice === 'theirs') {
+        const present = succeeded(await run(exec, dir, ['cat-file', '-e', `:${choice === 'mine' ? 2 : 3}:${path}`]));
+        if (present) {
+            await git(exec, dir, ['checkout', `--${choice === 'mine' ? 'ours' : 'theirs'}`, '--', path]);
+            await git(exec, dir, ['add', '--', path]);
+        }
+        else {
+            await git(exec, dir, ['rm', '--quiet', '--', path]);
+        }
+        return;
+    }
+    if (choice.content === null) {
+        await git(exec, dir, ['rm', '--quiet', '--force', '--', path]);
+        return;
+    }
+    if (hasConflictMarkers(choice.content))
+        throw new HubError(`${path} vẫn còn dấu xung đột (<<<<<<<, >>>>>>>).`);
+    writeFileSync(join(dir, path), choice.content, 'utf8');
+    await git(exec, dir, ['add', '--', path]);
+}
+/** Paths still unmerged in the draft. */
+export async function unresolved(dir, exec = defaultExec) {
+    return (await git(exec, dir, ['diff', '--name-only', '--diff-filter=U'])).split('\n').filter(Boolean);
+}
+/**
+ * Checks the merged draft with the framework's own tests, then moves `main` onto it and tags the old position.
+ * On any failure the draft is dropped and `main` is left exactly as it was.
+ */
+export async function finishUpdate(hub, draft, python, exec = defaultExec) {
+    const fail = async (error, output) => {
+        await removeDraft(hub, exec);
+        return { ok: false, error, output };
+    };
+    try {
+        const left = await unresolved(draft.dir, exec);
+        if (left.length > 0)
+            return { ok: false, error: `Còn ${left.length} xung đột chưa giải quyết: ${left.join(', ')}.` };
+        if (!python)
+            return { ok: false, error: 'Không tìm thấy Python để chạy test của framework; cập nhật chưa được áp dụng.' };
+        const tests = await exec(python.command, [...python.args, '-B', '-m', 'unittest', 'discover', '-s', '.agents/evals/tests', '-p', 'test_*.py'], { cwd: draft.dir, timeoutMs: 300_000 });
+        if (!succeeded(tests))
+            return fail('Test của framework không qua trên bản nháp; Hub giữ nguyên.', `${tests.stderr}\n${tests.stdout}`.trim());
+        const message = [`Update framework to ${draft.tag}`, '', 'Pirl-Source: update'].join('\n');
+        await git(exec, draft.dir, ['commit', '--quiet', '--no-verify', '-m', message], TOOL_AUTHOR);
+        await assertClean(hub, exec);
+        let preTag = `${PRE_UPDATE}${draft.tag}`;
+        for (let n = 2; succeeded(await run(exec, hub, ['rev-parse', '--verify', '--quiet', `refs/tags/${preTag}`])); n++)
+            preTag = `${PRE_UPDATE}${draft.tag}-${n}`;
+        await git(exec, hub, ['tag', preTag, MAIN]);
+        await git(exec, hub, ['merge', '--ff-only', '--quiet', DRAFT_BRANCH]);
+        await removeDraft(hub, exec);
+        return { ok: true, tag: draft.tag, preTag };
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+}
+export const draftExists = (hub) => existsSync(draftDir(hub));
+/** A unified diff between two texts (null is an absent file), for showing what each side of a conflict changed. */
+export async function textDiff(from, to, exec = defaultExec) {
+    const dir = mkdtempSync(join(tmpdir(), 'pirl-diff-'));
+    try {
+        writeFileSync(join(dir, 'a'), from ?? '', 'utf8');
+        writeFileSync(join(dir, 'b'), to ?? '', 'utf8');
+        // Exit code 1 means the texts differ; the diff is still on stdout.
+        const result = await exec('git', ['diff', '--no-index', '--no-color', 'a', 'b'], { cwd: dir, timeoutMs: 30_000 });
+        return result.stdout;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Commits changes the user made to the Hub by hand, before an update or a restore needs a clean Hub. */
+export async function commitUncommitted(hub, files, exec = defaultExec) {
+    await git(exec, hub, ['add', '--all', '--', ...files]);
+    const message = ['Manual framework change', '', 'Pirl-Source: manual'].join('\n');
+    await git(exec, hub, ['commit', '--quiet', '-m', message, '--', ...files], await identity(hub, exec));
+}

package/dist/providers/claude.js

@@ -0,0 +1,62 @@
+import { succeeded } from '../core/exec.js';
+const AUTH_LABELS = {
+    oauth_token: 'tài khoản Claude (subscription)',
+    claude_ai: 'tài khoản Claude (subscription)',
+    api_key: 'API key',
+};
+export function parseAuthStatus(stdout) {
+    try {
+        const data = JSON.parse(stdout);
+        const method = typeof data.authMethod === 'string' ? data.authMethod : undefined;
+        const viaCloud = typeof data.apiProvider === 'string' && data.apiProvider !== 'firstParty' ? data.apiProvider : undefined;
+        return {
+            loggedIn: data.loggedIn === true,
+            authMethod: viaCloud ?? (method ? (AUTH_LABELS[method] ?? method) : undefined),
+        };
+    }
+    catch {
+        return { loggedIn: null };
+    }
+}
+/** `--agents` read from a file needs 2.1.281; `--permission-prompts` needs 2.1.259. */
+export const MIN_CLAUDE_VERSION = '2.1.281';
+export function versionAtLeast(version, minimum) {
+    const parse = (text) => text.split('.').map(part => Number.parseInt(part, 10) || 0);
+    const [a, b] = [parse(version), parse(minimum)];
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    }
+    return true;
+}
+export const claudeProvider = {
+    id: 'claude',
+    label: 'Claude Code',
+    available: true,
+    async detect(exec) {
+        const version = await exec('claude', ['--version'], { timeoutMs: 15_000 });
+        if (!succeeded(version)) {
+            return {
+                installed: false,
+                loggedIn: null,
+                fix: 'Cài Claude Code theo hướng dẫn tại https://code.claude.com/docs, rồi chạy `claude` một lần để đăng nhập.',
+            };
+        }
+        // `claude auth status` reports sign-in state as JSON without exposing any credential.
+        const status = await exec('claude', ['auth', 'status', '--json'], { timeoutMs: 15_000 });
+        const auth = succeeded(status) || status.stdout.trim() ? parseAuthStatus(status.stdout) : { loggedIn: null };
+        const found = version.stdout.trim().split(/\s+/)[0] ?? '';
+        const outdated = found !== '' && !versionAtLeast(found, MIN_CLAUDE_VERSION);
+        return {
+            installed: true,
+            version: found,
+            ...auth,
+            outdated,
+            fix: auth.loggedIn === false
+                ? 'Chạy `claude` (hoặc `claude auth login`) để đăng nhập bằng tài khoản của bạn.'
+                : outdated
+                    ? `PIRL cần Claude Code ${MIN_CLAUDE_VERSION} trở lên. Chạy \`claude update\`.`
+                    : undefined,
+        };
+    },
+};

package/dist/providers/index.js

@@ -0,0 +1,17 @@
+import { claudeProvider } from './claude.js';
+const planned = (id, label) => ({
+    id,
+    label,
+    available: false,
+    detect: async () => ({ installed: false, loggedIn: null, fix: `${label} sẽ được hỗ trợ ở giai đoạn sau.` }),
+});
+/** Claude Code is the pilot provider; the others are listed so /settings can show what is coming. */
+export const PROVIDERS = [
+    claudeProvider,
+    planned('codex', 'Codex CLI'),
+    planned('gemini', 'Gemini CLI'),
+    planned('copilot', 'Copilot CLI'),
+];
+export function getProvider(id) {
+    return PROVIDERS.find(provider => provider.id === id) ?? claudeProvider;
+}

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};