pirl-framework-cli 0.0.0-stage → 1.0.0

package/dist/core/paths.js

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** `~/.pirl` (`%USERPROFILE%\.pirl` on Windows). PIRL_HOME moves it, which tests use to stay off the real home. */
+export function pirlHome(env = process.env) {
+    return env['PIRL_HOME'] || join(homedir(), '.pirl');
+}
+export const hubDir = (home) => join(home, 'hub');
+/** Paths under the user's home are shown as `~/…`, which keeps them short and readable in the TUI. */
+export function displayPath(path, home = homedir()) {
+    if (!home)
+        return path;
+    if (path === home)
+        return '~';
+    // Either separator: Windows accepts both, and paths reach here from Git and from the user's shell.
+    return path.startsWith(home + sep) || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+export const configFile = (home) => join(home, 'config.json');
+/** The directory holding this package's package.json, found from the running file (src/ in dev, dist/ when built). */
+export function packageRoot(from = fileURLToPath(import.meta.url)) {
+    let dir = dirname(from);
+    while (!existsSync(join(dir, 'package.json'))) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error('package.json of PIRL CLI not found');
+        dir = parent;
+    }
+    return dir;
+}
+export function packageInfo(root = packageRoot()) {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    return { name: pkg.name, version: pkg.version };
+}

package/dist/core/targetRepo.js

@@ -0,0 +1,22 @@
+import { basename } from 'node:path';
+import { exec as defaultExec, succeeded } from './exec.js';
+/**
+ * The target repository is the Git repository holding the directory where `pirl` was started.
+ * From a subdirectory, its repository root is used. Outside any repository the TUI still opens,
+ * but the layers stay locked.
+ */
+export async function detectTargetRepo(cwd, exec = defaultExec) {
+    const top = await exec('git', ['rev-parse', '--show-toplevel'], { cwd, timeoutMs: 10_000 });
+    if (top.error)
+        return { kind: 'none', cwd, reason: 'Không tìm thấy Git' };
+    if (!succeeded(top))
+        return { kind: 'none', cwd, reason: 'Thư mục hiện tại không nằm trong git repo' };
+    const root = top.stdout.trim();
+    const head = await exec('git', ['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd: root, timeoutMs: 10_000 });
+    let branch = succeeded(head) ? head.stdout.trim() : null;
+    if (!branch) {
+        const sha = await exec('git', ['rev-parse', '--short', 'HEAD'], { cwd: root, timeoutMs: 10_000 });
+        branch = succeeded(sha) ? `@${sha.stdout.trim()}` : null;
+    }
+    return { kind: 'git', root, name: basename(root), branch };
+}

package/dist/doctor/doctor.js

@@ -0,0 +1,95 @@
+import { succeeded } from '../core/exec.js';
+export const MIN_NODE_MAJOR = 22;
+export const MIN_PYTHON = [3, 9];
+export function nodeCheck(version = process.versions.node) {
+    const major = Number(version.split('.')[0]);
+    return major >= MIN_NODE_MAJOR
+        ? { id: 'node', label: 'Node.js', state: 'ok', detail: `v${version}` }
+        : { id: 'node', label: 'Node.js', state: 'fail', detail: `v${version}`, fix: `Cài Node.js ${MIN_NODE_MAJOR} trở lên.` };
+}
+export async function gitCheck(exec) {
+    const result = await exec('git', ['--version'], { timeoutMs: 10_000 });
+    return succeeded(result)
+        ? { id: 'git', label: 'Git', state: 'ok', detail: result.stdout.trim().replace(/^git version\s*/, '') }
+        : { id: 'git', label: 'Git', state: 'fail', detail: 'Không tìm thấy', fix: 'Cài Git và đảm bảo lệnh `git` chạy được trong terminal.' };
+}
+/** The Windows `py` launcher comes first there; the Microsoft Store `python3` stub fails the version parse and is skipped. */
+export function pythonCandidates(platform = process.platform) {
+    const plain = [
+        { command: 'python3', args: [] },
+        { command: 'python', args: [] },
+    ];
+    return platform === 'win32' ? [{ command: 'py', args: ['-3'] }, ...plain.reverse()] : plain;
+}
+export function parsePythonVersion(output) {
+    const match = /Python (\d+)\.(\d+)(\.\d+)?/.exec(output);
+    return match ? [Number(match[1]), Number(match[2]), `${match[1]}.${match[2]}${match[3] ?? ''}`] : null;
+}
+export async function findPython(exec, platform = process.platform) {
+    let tooOld = null;
+    for (const candidate of pythonCandidates(platform)) {
+        const result = await exec(candidate.command, [...candidate.args, '--version'], { timeoutMs: 10_000 });
+        const parsed = succeeded(result) ? parsePythonVersion(result.stdout + result.stderr) : null;
+        if (!parsed)
+            continue;
+        const [major, minor, version] = parsed;
+        if (major > MIN_PYTHON[0] || (major === MIN_PYTHON[0] && minor >= MIN_PYTHON[1])) {
+            const python = { ...candidate, version };
+            return { python, check: { id: 'python', label: 'Python', state: 'ok', detail: `${version} (${[candidate.command, ...candidate.args].join(' ')})` } };
+        }
+        tooOld ??= version;
+    }
+    const need = `${MIN_PYTHON[0]}.${MIN_PYTHON[1]}`;
+    return {
+        python: null,
+        check: {
+            id: 'python',
+            label: 'Python',
+            state: 'fail',
+            detail: tooOld ? `${tooOld} quá cũ` : 'Không tìm thấy',
+            fix: `Cài Python ${need} trở lên; các công cụ của framework (validator, record) chạy bằng Python.`,
+        },
+    };
+}
+export async function providerCheck(provider, exec) {
+    const base = { id: 'provider', label: provider.label };
+    if (!provider.available)
+        return { ...base, state: 'fail', detail: 'Chưa được hỗ trợ', fix: 'Chọn Claude Code trong /settings.' };
+    const found = await provider.detect(exec);
+    if (!found.installed)
+        return { ...base, state: 'fail', detail: 'Chưa cài', fix: found.fix };
+    const version = found.version ? `${found.version} · ` : '';
+    if (found.loggedIn === false)
+        return { ...base, state: 'fail', detail: `${version}chưa đăng nhập`, fix: found.fix };
+    if (found.outdated)
+        return { ...base, state: 'fail', detail: `${version}cần bản mới hơn`, fix: found.fix };
+    if (found.loggedIn === null)
+        return { ...base, state: 'warn', detail: `${version}không xác định được trạng thái đăng nhập` };
+    return { ...base, state: 'ok', detail: `${version}đã đăng nhập${found.authMethod ? ` bằng ${found.authMethod}` : ''}` };
+}
+export function hubCheck(status, error) {
+    const base = { id: 'hub', label: 'Hub' };
+    if (!status)
+        return { ...base, state: 'fail', detail: error ?? 'Chưa tạo được Hub' };
+    if (status.branch !== 'main') {
+        return { ...base, state: 'warn', detail: `Đang ở nhánh ${status.branch ?? '(không có)'}`, fix: `Chuyển Hub (${status.path}) về nhánh main.` };
+    }
+    const parts = [status.upstreamTag ?? 'không rõ phiên bản', `${status.localImprovements} cải tiến cục bộ`];
+    if (status.uncommitted.length > 0)
+        parts.push(`${status.uncommitted.length} thay đổi chưa commit`);
+    if (status.updateAvailable)
+        parts.push(`có framework ${status.bundledVersion} mới`);
+    return { ...base, state: status.uncommitted.length > 0 ? 'warn' : 'ok', detail: parts.join(' · ') };
+}
+export function targetCheck(target) {
+    return target.kind === 'git'
+        ? { id: 'target', label: 'Target repo', state: 'ok', detail: `${target.root}${target.branch ? ` (${target.branch})` : ''}` }
+        : { id: 'target', label: 'Target repo', state: 'warn', detail: target.reason, fix: 'Mở `pirl` trong thư mục của một git repo để dùng các layer.' };
+}
+export async function runDoctor(input) {
+    const [git, python, provider] = await Promise.all([gitCheck(input.exec), findPython(input.exec), providerCheck(input.provider, input.exec)]);
+    return {
+        checks: [nodeCheck(), git, python.check, provider, hubCheck(input.hub, input.hubError), targetCheck(input.target)],
+        python: python.python,
+    };
+}

package/dist/engine/agentMerge.js

@@ -0,0 +1,71 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { hasConflictMarkers } from '../hub/update.js';
+import { ruleRoot, WAITING_TOOLS } from './permissions.js';
+/** Where the three versions and the merged result live during the proposal, inside the draft's ignored `.tmp/`. */
+const WORK = join('.tmp', 'pirl-merge');
+const SYSTEM_PROMPT = (dir, path) => [
+    'You merge one file of the PIRL framework during a framework update. Nothing else is in scope.',
+    `The file is \`${path}\`. Its versions are in ${dir}:`,
+    '- `base`: the original version both sides started from;',
+    '- `mine`: the user\'s version, carrying their local improvements;',
+    '- `theirs`: the new original version.',
+    `Read the three, then write the merged file to ${join(dir, 'merged')} with the Write tool.`,
+    'Keep every change of `theirs` and every local improvement of `mine`. Where both change the same passage, write one passage that carries both intentions. When they contradict, prefer `theirs`, unless the local change makes a rule stricter.',
+    'Never loosen, narrow or remove a safety rule (AGENTS.md, "Safety rules and self-improvement", defines them); where a safety rule differs between the versions, keep the stricter wording.',
+    'The merged file holds only the file content: no conflict markers, no comments about the merge.',
+    'Then reply in the language of the file\'s user, Vietnamese, in at most four short sentences: what each side changed and how you combined them.',
+].join('\n');
+/**
+ * Asks the provider for a merged version of one conflicted file. Nothing is applied here: the proposal goes to the
+ * user, who accepts it or picks another resolution. The provider may read the draft and write only the result file.
+ */
+export async function proposeMerge(runner, draftDir, conflict, model) {
+    const work = join(draftDir, WORK);
+    rmSync(work, { recursive: true, force: true });
+    mkdirSync(work, { recursive: true });
+    try {
+        writeFileSync(join(work, 'base'), conflict.base ?? '', 'utf8');
+        writeFileSync(join(work, 'mine'), conflict.mine ?? '', 'utf8');
+        writeFileSync(join(work, 'theirs'), conflict.theirs ?? '', 'utf8');
+        const improvements = conflict.myCommits.map(commit => `- ${commit.subject}${commit.record ? ` (record ${commit.record})` : ''}`);
+        const prompt = [
+            `Merge \`${conflict.path}\`.`,
+            ...(improvements.length ? ['The local improvements in `mine` came from:', ...improvements] : []),
+        ].join('\n');
+        const merged = join(work, 'merged');
+        let reply = null;
+        const handle = runner.start({
+            cwd: draftDir,
+            addDirs: [],
+            prompt,
+            systemPrompt: SYSTEM_PROMPT(work, conflict.path),
+            agents: {},
+            permissions: {
+                allow: ['Read', 'Grep', 'Glob', `Edit(${ruleRoot(merged)})`],
+                deny: ['Bash', 'Agent', 'WebFetch', 'WebSearch', ...WAITING_TOOLS],
+            },
+            model,
+        }, event => {
+            if (event.type === 'result')
+                reply = event;
+        });
+        const exit = await handle.done;
+        const result = reply;
+        if (!result || result.isError)
+            return { ok: false, error: result?.text || exit.stderr.trim().split('\n').slice(-2).join(' ') || `mã thoát ${exit.code}` };
+        let content;
+        try {
+            content = readFileSync(merged, 'utf8');
+        }
+        catch {
+            return { ok: false, error: 'Agent không ghi bản gộp.' };
+        }
+        if (hasConflictMarkers(content))
+            return { ok: false, error: 'Bản gộp của agent vẫn còn dấu xung đột.' };
+        return { ok: true, content, explanation: result.text.trim() };
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}

package/dist/engine/agents.js

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const CATALOG_FILE = '.agents/instructions/standalone-and-maintenance.instructions.md';
+/** Reads the role catalog table of the Hub's framework, the only list of role IDs. */
+export function readRoleCatalog(hub) {
+    const text = readFileSync(join(hub, CATALOG_FILE), 'utf8');
+    const section = text.slice(text.indexOf('### Role catalog'));
+    const roles = [];
+    for (const line of section.split('\n')) {
+        const match = /^\|\s*`([a-z-]+)`\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*$/.exec(line);
+        if (match)
+            roles.push({ id: match[1], expertise: match[2], usedIn: match[3].split(',').map(part => part.trim()) });
+    }
+    return roles;
+}
+/**
+ * The tools each role's subagent gets. Implementation roles edit files; the roles that trace code may run
+ * read-only Git commands; process-auditor improves framework files and runs the framework's checks.
+ * Which paths may be edited and which commands may run is limited further by the run's permission rules.
+ */
+export function roleTools(role) {
+    const read = ['Read', 'Grep', 'Glob'];
+    if (role.id === 'process-auditor')
+        return [...read, 'Edit', 'Write', 'Bash'];
+    if (role.usedIn.includes('implement'))
+        return role.id === 'technical-writer' ? [...read, 'Edit', 'Write'] : [...read, 'Edit', 'Write', 'Bash'];
+    if (role.id === 'code-analyst' || role.id === 'code-reviewer')
+        return [...read, 'Bash'];
+    return read;
+}
+/**
+ * How a role uses its tools under the run's permission rules (src/engine/permissions.ts). Subagents do not see the
+ * coordinator's host instructions, and a refused command costs a turn, so each role gets these rules itself.
+ */
+function toolRules(target) {
+    return [
+        'Read files with the Read, Grep and Glob tools, never with `cat`, `ls`, `grep`, `find` or `head` in Bash: the run refuses those.',
+        'Bash runs one command per call, without pipes or `;`. It is allowed only for: read-only Git (`log`, `show`, `diff`, `status`, `ls-files`, `rev-parse`, `blame`), the framework\'s Python tools run from the Hub root, and the test command the target repository documents.',
+        ...(target ? [`In the target repository, run Git as \`git -C ${target} <command>\` and tests as \`cd ${target} && <test command>\`.`] : []),
+        'Temporary files go under `.tmp/pirl-run/` in the Hub; `/tmp` and every path outside the Hub and the target repository are refused.',
+    ];
+}
+/**
+ * `model` is the roles' model alias; they run on the coordinator's model when it is left out. `target` is the run's
+ * target repository, named in the roles' command rules.
+ */
+export function roleAgents(hub, roles = readRoleCatalog(hub), model, target = null, effort) {
+    return Object.fromEntries(roles.map(role => [
+        role.id,
+        {
+            description: `PIRL role ${role.id}: ${role.expertise}. Delegate this role's assignment of a PIRL layer run to it.`,
+            prompt: [
+                `You are the PIRL role \`${role.id}\`.`,
+                `Before anything else, read \`${join(hub, '.agents', 'roles', `${role.id}.role.md`)}\` and apply it.`,
+                'Work only on the assignment the coordinator gave you, with the sources, constraints and settled direction it names.',
+                'Support every conclusion with its source: file path and symbol, command and result, or the rule that applies.',
+                'Do not read drafts or conclusions of other roles of this run unless your assignment hands them to you.',
+                'Report every reviewer outside your role that you consulted. Never commit, push or change files your assignment does not cover.',
+                ...toolRules(target),
+            ].join('\n'),
+            tools: roleTools(role),
+            ...(model ? { model } : {}),
+            // Set on every role, not left to inheritance, so the roles reason at the level the user chose.
+            ...(effort ? { effort } : {}),
+        },
+    ]));
+}

package/dist/engine/attachments.js

@@ -0,0 +1,251 @@
+import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep, win32 } from 'node:path';
+import { exec as defaultExec, succeeded } from '../core/exec.js';
+/** Directories never listed: version control, dependencies and caches, which a repository's .gitignore usually leaves out. */
+const SKIPPED = new Set(['.git', 'node_modules', '.venv', 'venv', '__pycache__', '.tox', '.mypy_cache', '.pytest_cache', '.next', '.turbo', '.cache']);
+/** Most entries an index or a folder listing walks; a bigger tree is cut there. */
+export const WALK_LIMIT = 20_000;
+/** Files under `dir` (relative, `/` separators) by walking it, skipping SKIPPED, up to `limit` files. */
+function walk(dir, limit) {
+    const files = [];
+    const pending = [''];
+    while (pending.length > 0 && files.length < limit) {
+        const current = pending.shift();
+        let names;
+        try {
+            names = readdirSync(join(dir, current), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        names.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of names) {
+            const path = current ? `${current}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!SKIPPED.has(entry.name))
+                    pending.push(path);
+            }
+            else if (entry.isFile()) {
+                files.push(path);
+                if (files.length >= limit)
+                    break;
+            }
+        }
+    }
+    return files;
+}
+/** Files of `dir`: those Git tracks or would track (so .gitignore applies) inside a repository, else a walk. */
+async function filesOf(dir, exec) {
+    const listed = await exec('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], { cwd: dir, timeoutMs: 20_000 });
+    if (succeeded(listed))
+        return listed.stdout.split('\0').filter(Boolean).slice(0, WALK_LIMIT);
+    return walk(dir, WALK_LIMIT);
+}
+/** The files under `base` and every folder holding them, for completing `@` mentions. */
+export async function pathIndex(base, exec = defaultExec) {
+    const files = await filesOf(base, exec);
+    const folders = new Set();
+    for (const file of files) {
+        for (let at = file.indexOf('/'); at > 0; at = file.indexOf('/', at + 1))
+            folders.add(file.slice(0, at));
+    }
+    return [...[...folders].map(path => ({ path, folder: true })), ...files.map(path => ({ path, folder: false }))];
+}
+const basename = (path) => path.slice(path.lastIndexOf('/') + 1);
+/**
+ * Paths for a mention being typed, best first. Nothing typed lists the top level; `folder/` lists that folder,
+ * itself first so Enter can attach it. Otherwise: paths starting with the text, then names starting with it,
+ * then names and paths containing it; folders first, shorter paths first.
+ */
+export function suggestPaths(index, query, limit = 50) {
+    const typed = query.toLowerCase().replace(/\\/g, '/');
+    const byOrder = (a, b) => Number(b.folder) - Number(a.folder) || a.path.length - b.path.length || a.path.localeCompare(b.path);
+    if (typed === '' || typed.endsWith('/')) {
+        const parent = typed.replace(/\/$/, '');
+        const self = index.find(entry => entry.folder && entry.path.toLowerCase() === parent);
+        const children = index.filter(entry => {
+            const path = entry.path.toLowerCase();
+            if (parent && !path.startsWith(`${parent}/`))
+                return false;
+            return !path.slice(parent ? parent.length + 1 : 0).includes('/');
+        });
+        return [...(self ? [self] : []), ...children.sort(byOrder)].slice(0, limit);
+    }
+    const rank = (entry) => {
+        const path = entry.path.toLowerCase();
+        const name = basename(path);
+        if (path.startsWith(typed))
+            return 0;
+        if (name.startsWith(typed))
+            return 1;
+        if (name.includes(typed))
+            return 2;
+        if (path.includes(typed))
+            return 3;
+        return -1;
+    };
+    return index
+        .map(entry => ({ entry, score: rank(entry) }))
+        .filter(item => item.score >= 0)
+        .sort((a, b) => a.score - b.score || byOrder(a.entry, b.entry))
+        .slice(0, limit)
+        .map(item => item.entry);
+}
+/** How a path is written after `@`: quoted when it has spaces; a folder ends with `/`. */
+export const mentionText = (entry) => {
+    const path = entry.folder ? `${entry.path}/` : entry.path;
+    return /\s/.test(path) ? `@"${path}"` : `@${path}`;
+};
+/** Every `@path` and `@"path"` in the text, written after a space or at the start (so an e-mail address is not one). */
+export function findMentions(text) {
+    const found = [];
+    for (const match of text.matchAll(/(^|\s)@(?:"([^"]+)"|([^\s"]+))/g))
+        found.push(match[2] ?? match[3]);
+    return found;
+}
+/**
+ * The share or device a Windows path starts with (`\\host\share\`, `\\?\C:\`, `\\.\pipe\`), or null for a
+ * local path. Windows takes any two separators at the start as one, so `//host/share` and `/\host\share` count too.
+ * Elsewhere `//tmp/x` is an ordinary local path and `\` an ordinary character: null.
+ */
+export function remoteRoot(path, platform = process.platform) {
+    if (platform !== 'win32' || !/^[\\/]{2}/.test(path))
+        return null;
+    return win32.parse(win32.normalize(path)).root.toLowerCase();
+}
+/**
+ * The path a mention names, if it exists: `~/` is the home directory; a relative path is read from `base`, then from `cwd`.
+ * On Windows a path on a network share or a device is never looked at unless the base, the start directory or the
+ * home directory is on that same share: merely reading it would connect to the host (SMB, or WebDAV for
+ * `\\host@80\x`) and send it the user's NTLM credentials, and a mention can come from pasted text.
+ */
+function locate(mention, base, cwd, platform) {
+    const candidates = mention.startsWith('~/') || mention === '~' ? [join(homedir(), mention.slice(1))] : isAbsolute(mention) ? [resolve(mention)] : [resolve(base, mention), resolve(cwd, mention)];
+    const trusted = [base, cwd, homedir()].map(dir => remoteRoot(dir, platform)).filter((root) => root !== null);
+    const untrusted = (path) => {
+        const root = remoteRoot(path, platform);
+        return root !== null && !trusted.includes(root);
+    };
+    // The mention as written and each path it resolves to: either one naming a share is enough to skip it.
+    if (untrusted(mention))
+        return null;
+    for (const candidate of candidates) {
+        if (untrusted(candidate))
+            continue;
+        try {
+            const stat = statSync(candidate);
+            if (stat.isDirectory())
+                return { path: candidate, kind: 'folder', size: 0 };
+            if (stat.isFile())
+                return { path: candidate, kind: 'file', size: stat.size };
+        }
+        catch {
+            // not this one
+        }
+    }
+    return null;
+}
+/**
+ * The mentions of the text that name an existing file or folder, once each. A mention followed by punctuation
+ * ("xem @src/a.ts, rồi…") still names the path without it. Mentions that name nothing stay plain text.
+ */
+export function resolveMentions(text, base, cwd = base, platform = process.platform) {
+    const attachments = [];
+    const seen = new Set();
+    for (const mention of findMentions(text)) {
+        const trimmed = mention.replace(/[.,;:!?)\]}'"]+$/, '');
+        const found = locate(mention, base, cwd, platform) ?? (trimmed && trimmed !== mention ? locate(trimmed, base, cwd, platform) : null);
+        if (!found || seen.has(found.path))
+            continue;
+        seen.add(found.path);
+        const inside = relative(base, found.path);
+        const display = inside && !inside.startsWith('..') && !isAbsolute(inside) ? inside.split(sep).join('/') : found.path;
+        attachments.push({ mention, path: found.path, display: found.kind === 'folder' ? `${display.replace(/\/$/, '')}/` : display, kind: found.kind, size: found.size });
+    }
+    return attachments;
+}
+/** A file's content goes with the request up to this size; a bigger one is sent as its path, for the agent to read. */
+export const FILE_LIMIT = 100_000;
+/** All included contents together stay under this; files past it are sent as paths. */
+export const TOTAL_LIMIT = 300_000;
+/** Files a folder lists with its path; a bigger folder says how many more it holds. */
+export const FOLDER_LIMIT = 300;
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(bytes < 10 * 1024 ? 1 : 0)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+/** Text files only: a NUL byte in the first 8 KB marks a binary file (an image, a PDF, an archive). */
+function isBinary(path) {
+    const buffer = Buffer.alloc(8192);
+    let fd = null;
+    try {
+        fd = openSync(path, 'r');
+        const read = readSync(fd, buffer, 0, buffer.length, 0);
+        return buffer.subarray(0, read).includes(0);
+    }
+    catch {
+        return true;
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+/** A Markdown fence longer than any run of backticks in the text, so the text cannot close it. */
+function fence(text) {
+    const longest = Math.max(2, ...[...text.matchAll(/`+/g)].map(match => match[0].length));
+    return '`'.repeat(longest + 1);
+}
+/** The request's context from its attachments: contents of text files within the limits, paths for the rest, file lists of folders. */
+export async function attachmentContext(attachments, roots, exec = defaultExec) {
+    if (attachments.length === 0)
+        return { text: '', dirs: [], summary: [] };
+    const inside = (path) => roots.some(root => {
+        const rel = relative(root, path);
+        return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+    });
+    const dirs = new Set();
+    const summary = [];
+    const parts = [
+        '# Attached by the user',
+        '',
+        'The user attached these paths with `@` in the request above. They are part of the request: read what bears on the task in full, and give the relevant paths to every role you delegate to, since roles do not see this message.',
+    ];
+    let total = 0;
+    for (const item of attachments) {
+        if (item.kind === 'folder' && !inside(item.path))
+            dirs.add(item.path);
+        if (item.kind === 'folder') {
+            const files = await filesOf(item.path, exec);
+            const shown = files.slice(0, FOLDER_LIMIT);
+            parts.push('', `## Folder: ${item.display} (${item.path}, ${files.length >= WALK_LIMIT ? `${WALK_LIMIT}+` : files.length} files)`, '');
+            parts.push(...shown.map(file => `- ${file}`));
+            if (files.length > shown.length)
+                parts.push(`- … and ${files.length - shown.length} more; list them with Glob.`);
+            summary.push({ display: item.display, detail: `thư mục, ${files.length} file: gửi danh sách file` });
+            continue;
+        }
+        const heading = `## File: ${item.display} (${item.path}, ${formatSize(item.size)})`;
+        if (isBinary(item.path)) {
+            parts.push('', heading, '', 'Not text (an image, a PDF or another binary file): read it with Read if it bears on the task.');
+            summary.push({ display: item.display, detail: `${formatSize(item.size)}, không phải văn bản: gửi đường dẫn` });
+            continue;
+        }
+        if (item.size > FILE_LIMIT || total + item.size > TOTAL_LIMIT) {
+            parts.push('', heading, '', 'Too large to include here: read it with Read, in parts where needed.');
+            summary.push({ display: item.display, detail: `${formatSize(item.size)}, quá lớn để gửi kèm: gửi đường dẫn`, tone: 'warning' });
+            continue;
+        }
+        const content = readFileSync(item.path, 'utf8');
+        total += item.size;
+        const marks = fence(content);
+        const name = basename(item.display);
+        parts.push('', heading, '', `${marks}${name.includes('.') ? name.slice(name.lastIndexOf('.') + 1) : ''}`, content.replace(/\n$/, ''), marks);
+        summary.push({ display: item.display, detail: `${formatSize(item.size)}: gửi kèm nội dung` });
+    }
+    return { text: parts.join('\n'), dirs: [...dirs], summary };
+}

package/dist/engine/claudeQuota.js

@@ -0,0 +1,62 @@
+import spawn from 'cross-spawn';
+const KIND_LABELS = { session: '5 giờ', weekly_all: 'Tuần' };
+function labelOf(row) {
+    const kind = String(row['kind'] ?? '');
+    const scope = (row['scope'] ?? {});
+    const name = scope['model']?.display_name ?? scope['surface']?.display_name;
+    if (KIND_LABELS[kind])
+        return KIND_LABELS[kind];
+    if (String(row['group'] ?? '') === 'weekly' || kind.startsWith('weekly'))
+        return name ? `Tuần (${name})` : 'Tuần';
+    return name ?? kind;
+}
+/** The meters in one stream-json line, or null when the line has none (an API key login has no plan meters). */
+export function parseQuotaLine(line) {
+    let data;
+    try {
+        data = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (data['type'] !== 'assistant')
+        return null;
+    const message = (data['message'] ?? {});
+    const report = (data['usage_report'] ?? message['usage_report']);
+    const limits = report?.rate_limits?.limits;
+    if (!Array.isArray(limits))
+        return null;
+    return limits
+        .filter(row => typeof row['percent'] === 'number')
+        .map(row => ({ kind: String(row['kind'] ?? ''), label: labelOf(row), percent: row['percent'], resetsAt: typeof row['resets_at'] === 'string' ? row['resets_at'] : null }));
+}
+/** Null when the meters cannot be read: no subscription, an old Claude Code, a rate-limited usage endpoint. */
+export function readClaudeQuota(command = 'claude', cwd, timeoutMs = 20_000) {
+    return new Promise(resolve => {
+        let rows = null;
+        let buffer = '';
+        const child = spawn(command, ['-p', '--output-format', 'stream-json', '--verbose', '--no-session-persistence'], {
+            cwd,
+            stdio: ['pipe', 'pipe', 'ignore'],
+            windowsHide: true,
+        });
+        const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+        child.stdout?.setEncoding('utf8').on('data', (chunk) => {
+            buffer += chunk;
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines)
+                rows = parseQuotaLine(line) ?? rows;
+        });
+        child.once('error', () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+        child.once('close', () => {
+            clearTimeout(timer);
+            resolve(parseQuotaLine(buffer) ?? rows);
+        });
+        child.stdin?.on('error', () => { });
+        child.stdin?.end('/usage');
+    });
+}