@birdie_moblie/open_spec 2.1.7

package/dist/shared/fs.d.ts

@@ -0,0 +1,18 @@
+export declare function exists(target: string): boolean;
+export declare function ensureDir(dir: string): void;
+export declare function readText(file: string): string;
+export declare function writeText(file: string, content: string): void;
+export declare function readJson<T>(file: string): T;
+export declare function writeJson(file: string, value: unknown): void;
+export declare function appendText(file: string, line: string): void;
+export declare function copyDir(from: string, to: string): void;
+export declare function copyPath(from: string, to: string, options?: {
+    excludeNames?: string[];
+}): void;
+export declare function removePath(target: string): void;
+export declare function listDirs(dir: string): string[];
+export declare function listFilesRecursive(dir: string): string[];
+export declare function readFileBytes(file: string): Buffer;
+export declare function readSymlink(file: string): string;
+export declare function isSymlink(file: string): boolean;
+//# sourceMappingURL=fs.d.ts.map

package/dist/shared/fs.js

@@ -0,0 +1,93 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { AppError } from './errors.js';
+export function exists(target) {
+    return existsSync(target);
+}
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+export function readText(file) {
+    return readFileSync(file, 'utf8');
+}
+export function writeText(file, content) {
+    ensureDir(path.dirname(file));
+    writeFileSync(file, content, 'utf8');
+}
+export function readJson(file) {
+    try {
+        return JSON.parse(readText(file));
+    }
+    catch (error) {
+        throw new AppError('invalid_json', `JSON 文件无法解析: ${file}`, error instanceof Error ? error.message : String(error));
+    }
+}
+export function writeJson(file, value) {
+    ensureDir(path.dirname(file));
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        renameSync(temporary, file);
+    }
+    catch (error) {
+        if (exists(temporary))
+            unlinkSync(temporary);
+        throw error;
+    }
+}
+export function appendText(file, line) {
+    ensureDir(path.dirname(file));
+    writeFileSync(file, line, { encoding: 'utf8', flag: 'a' });
+}
+export function copyDir(from, to) {
+    ensureDir(to);
+    cpSync(from, to, { recursive: true });
+}
+export function copyPath(from, to, options = {}) {
+    ensureDir(path.dirname(to));
+    const excluded = new Set(options.excludeNames ?? []);
+    cpSync(from, to, {
+        recursive: true,
+        filter: excluded.size === 0 ? undefined : (source) => !excluded.has(path.basename(source)),
+    });
+}
+export function removePath(target) {
+    rmSync(target, { recursive: true, force: true });
+}
+export function listDirs(dir) {
+    if (!exists(dir))
+        return [];
+    return readdirSync(dir).filter((name) => {
+        try {
+            return statSync(path.join(dir, name)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function listFilesRecursive(dir) {
+    if (!exists(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        const full = path.join(dir, name);
+        const stat = lstatSync(full);
+        if (stat.isDirectory())
+            out.push(...listFilesRecursive(full));
+        else
+            out.push(full);
+    }
+    return out;
+}
+export function readFileBytes(file) {
+    return readFileSync(file);
+}
+export function readSymlink(file) {
+    return readlinkSync(file);
+}
+export function isSymlink(file) {
+    return lstatSync(file).isSymbolicLink();
+}
+//# sourceMappingURL=fs.js.map

package/dist/shared/git.d.ts

@@ -0,0 +1,22 @@
+export interface GitSnapshot {
+    available: boolean;
+    branch: string | null;
+    headSha: string | null;
+}
+export interface DiffBaseline {
+    snapshot: GitSnapshot;
+    entries: Record<string, DirtyEntry>;
+    capturedAt: string;
+}
+export interface DirtyEntry {
+    status: string;
+    fingerprint: string;
+}
+export declare function parseDiffBaseline(value: unknown): DiffBaseline;
+export declare function readGitSnapshot(projectRoot: string): GitSnapshot;
+export declare function captureDiffBaseline(projectRoot: string): DiffBaseline;
+/** Stable checkout identity, excluding workflow artifacts but retaining dirty host files. */
+export declare function checkoutFingerprint(projectRoot: string): string;
+/** 相对创建 worker 时的基线，得到本次实际改动的相对路径。 */
+export declare function changedFilesSince(projectRoot: string, baseline: DiffBaseline): string[];
+//# sourceMappingURL=git.d.ts.map

package/dist/shared/git.js

@@ -0,0 +1,132 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, readlinkSync } from 'node:fs';
+import { z } from 'zod';
+import { AppError } from './errors.js';
+import { sha256, sha256File } from './hash.js';
+import { isOpsxInternal, normalizeRel, resolveInside } from './paths.js';
+const DiffBaselineSchema = z.object({
+    snapshot: z.object({
+        available: z.boolean(),
+        branch: z.string().nullable(),
+        headSha: z.string().nullable(),
+    }).strict(),
+    entries: z.record(z.string(), z.object({ status: z.string(), fingerprint: z.string() }).strict()),
+    capturedAt: z.string(),
+}).strict();
+export function parseDiffBaseline(value) {
+    const parsed = DiffBaselineSchema.safeParse(value);
+    if (!parsed.success)
+        throw new AppError('invalid_worker_baseline', 'Worker Git baseline 不合法', parsed.error.issues);
+    return parsed.data;
+}
+function git(projectRoot, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function gitRaw(projectRoot, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch {
+        return null;
+    }
+}
+export function readGitSnapshot(projectRoot) {
+    const headSha = git(projectRoot, ['rev-parse', 'HEAD']);
+    if (!headSha)
+        return { available: false, branch: null, headSha: null };
+    const branch = git(projectRoot, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    return { available: true, branch: branch || null, headSha };
+}
+export function captureDiffBaseline(projectRoot) {
+    const snapshot = readGitSnapshot(projectRoot);
+    if (!snapshot.available) {
+        throw new AppError('git_required', 'code Worker 需要在 Git 仓库中运行');
+    }
+    const entries = readDirtyEntries(projectRoot);
+    return { snapshot, entries, capturedAt: new Date().toISOString() };
+}
+/** Stable checkout identity, excluding workflow artifacts but retaining dirty host files. */
+export function checkoutFingerprint(projectRoot) {
+    const baseline = captureDiffBaseline(projectRoot);
+    const entries = Object.entries(baseline.entries).filter(([file]) => !isOpsxInternal(file)).sort(([a], [b]) => a.localeCompare(b));
+    return sha256(JSON.stringify({ head: baseline.snapshot.headSha, entries }));
+}
+/** 相对创建 worker 时的基线，得到本次实际改动的相对路径。 */
+export function changedFilesSince(projectRoot, baseline) {
+    const currentSnapshot = readGitSnapshot(projectRoot);
+    if (!currentSnapshot.available) {
+        throw new AppError('git_required', 'code Worker 需要在 Git 仓库中运行');
+    }
+    if (currentSnapshot.headSha !== baseline.snapshot.headSha) {
+        throw new AppError('worker_git_head_changed', 'Worker 执行期间 Git HEAD 已变化，无法可信计算 changed-set');
+    }
+    const now = readDirtyEntries(projectRoot);
+    const files = new Set();
+    for (const [file, entry] of Object.entries(now)) {
+        if (isOpsxInternal(file))
+            continue;
+        const before = baseline.entries[file];
+        if (!before || before.fingerprint !== entry.fingerprint || before.status !== entry.status) {
+            files.add(file);
+        }
+    }
+    for (const [file, before] of Object.entries(baseline.entries)) {
+        if (isOpsxInternal(file))
+            continue;
+        if (now[file])
+            continue;
+        if (fingerprintPath(projectRoot, file) !== before.fingerprint)
+            files.add(file);
+    }
+    return [...files].sort();
+}
+function readDirtyEntries(projectRoot) {
+    const raw = gitRaw(projectRoot, ['status', '--porcelain=v1', '-z', '-uall']);
+    if (raw === null)
+        throw new AppError('git_status_failed', '无法读取 Git 工作树状态');
+    const records = raw.split('\0');
+    const entries = {};
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (!record || record.length < 4)
+            continue;
+        const status = record.slice(0, 2);
+        const relative = normalizeRel(record.slice(3));
+        if (!relative)
+            continue;
+        entries[relative] = { status, fingerprint: fingerprintPath(projectRoot, relative) };
+        if (status.includes('R') || status.includes('C')) {
+            const previous = normalizeRel(records[index + 1] ?? '');
+            index += 1;
+            if (previous) {
+                entries[previous] = { status: `${status}:source`, fingerprint: fingerprintPath(projectRoot, previous) };
+            }
+        }
+    }
+    return entries;
+}
+function fingerprintPath(projectRoot, relative) {
+    const file = resolveInside(projectRoot, relative, 'git_path_outside_project');
+    if (!existsSync(file))
+        return 'missing';
+    const stat = lstatSync(file);
+    if (stat.isSymbolicLink())
+        return sha256(`symlink:${readlinkSync(file)}`);
+    if (stat.isFile())
+        return sha256File(file);
+    return sha256(`type:${stat.mode}:${stat.size}`);
+}
+//# sourceMappingURL=git.js.map

package/dist/shared/hash.d.ts

@@ -0,0 +1,5 @@
+export declare function sha256(content: string | Buffer): string;
+/** 对目录内全部文件做稳定 digest，用于技能/插件安装校验。 */
+export declare function digestDirectory(dir: string): string;
+export declare function sha256File(file: string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/shared/hash.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+import { lstatSync } from 'node:fs';
+import path from 'node:path';
+import { listFilesRecursive, readFileBytes, readSymlink } from './fs.js';
+export function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** 对目录内全部文件做稳定 digest，用于技能/插件安装校验。 */
+export function digestDirectory(dir) {
+    const files = listFilesRecursive(dir).sort();
+    const hash = createHash('sha256');
+    for (const file of files) {
+        const stat = lstatSync(file);
+        // socket / fifo 等不可读取内容，也不属于可分发的插件产物
+        if (!stat.isFile() && !stat.isSymbolicLink())
+            continue;
+        const relative = path.relative(dir, file).replace(/\\/g, '/');
+        hash.update(relative);
+        hash.update('\0');
+        hash.update(stat.isSymbolicLink() ? `symlink:${readSymlink(file)}` : readFileBytes(file));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+export function sha256File(file) {
+    const stat = lstatSync(file);
+    return sha256(stat.isSymbolicLink() ? `symlink:${readSymlink(file)}` : readFileBytes(file));
+}
+//# sourceMappingURL=hash.js.map

package/dist/shared/paths.d.ts

@@ -0,0 +1,16 @@
+/** 把路径规范成仓库内相对 POSIX 路径。 */
+export declare function normalizeRel(value: string): string;
+export declare function ensureTrailingSlash(value: string): string;
+export declare function isInsideDir(file: string, dir: string): boolean;
+export declare function isOpsxInternal(file: string): boolean;
+export declare function matchPattern(file: string, pattern: string): boolean;
+/** 解析仓库内路径，并拒绝绝对路径、词法越界和已有 symlink 越界。 */
+export declare function resolveInside(root: string, relative: string, code?: string): string;
+/** 校验会被用作文件名的标识；不限制业务命名，只排除路径语义。 */
+export declare function assertPathToken(value: string, label: string): void;
+export declare function changeDir(changeName: string): string;
+export declare function archiveDir(stamp: string, changeName: string): string;
+export declare const OPENSPEC_DIR = "openspec";
+export declare const OPSX_DIR = ".opsx";
+export declare const CONFIG_FILES: readonly ["config.yaml", "config.yml"];
+//# sourceMappingURL=paths.d.ts.map

package/dist/shared/paths.js

@@ -0,0 +1,97 @@
+import path from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { AppError } from './errors.js';
+/** 把路径规范成仓库内相对 POSIX 路径。 */
+export function normalizeRel(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/{2,}/g, '/');
+}
+export function ensureTrailingSlash(value) {
+    const normalized = normalizeRel(value);
+    return normalized.endsWith('/') ? normalized : `${normalized}/`;
+}
+export function isInsideDir(file, dir) {
+    const relative = normalizeRel(file);
+    const prefix = ensureTrailingSlash(dir);
+    return relative === normalizeRel(dir) || relative.startsWith(prefix);
+}
+export function isOpsxInternal(file) {
+    const relative = normalizeRel(file);
+    return relative === '.opsx' || relative.startsWith('.opsx/')
+        || relative.includes('/.opsx/') || relative.endsWith('/.opsx')
+        || /^openspec\/changes\/[^/]+(?:\/|$)/.test(relative);
+}
+export function matchPattern(file, pattern) {
+    const normalizedFile = normalizeRel(file);
+    const normalizedPattern = normalizeRel(pattern);
+    if (!/[*?]/.test(normalizedPattern)) {
+        return normalizedFile === normalizedPattern || isInsideDir(normalizedFile, normalizedPattern);
+    }
+    if (normalizedPattern.startsWith('**/') && matchPattern(normalizedFile, normalizedPattern.slice(3))) {
+        return true;
+    }
+    return globToRegExp(normalizedPattern).test(normalizedFile);
+}
+/** 解析仓库内路径，并拒绝绝对路径、词法越界和已有 symlink 越界。 */
+export function resolveInside(root, relative, code = 'path_outside_root') {
+    const portable = normalizeRel(relative);
+    if (!relative || path.isAbsolute(relative) || /^[A-Za-z]:\//.test(portable) || portable.startsWith('/') || relative.includes('\0')) {
+        throw new AppError(code, `路径必须是非空相对路径: ${relative}`);
+    }
+    const rootAbs = path.resolve(root);
+    const target = path.resolve(rootAbs, portable);
+    assertContained(rootAbs, target, relative, code);
+    const rootReal = existsSync(rootAbs) ? realpathSync(rootAbs) : rootAbs;
+    let cursor = rootAbs;
+    for (const segment of path.relative(rootAbs, target).split(path.sep).filter(Boolean)) {
+        cursor = path.join(cursor, segment);
+        if (!existsSync(cursor))
+            continue;
+        const real = realpathSync(cursor);
+        assertContained(rootReal, real, relative, code);
+    }
+    return target;
+}
+/** 校验会被用作文件名的标识；不限制业务命名，只排除路径语义。 */
+export function assertPathToken(value, label) {
+    if (!value || value === '.' || value === '..' || /[\\/\0]/.test(value)) {
+        throw new AppError('invalid_path_token', `${label} 不能包含路径语义: ${value}`);
+    }
+}
+function assertContained(root, target, display, code) {
+    const relative = path.relative(root, target);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new AppError(code, `路径越出允许目录: ${display}`);
+    }
+}
+function globToRegExp(pattern) {
+    let source = '';
+    for (let i = 0; i < pattern.length; i += 1) {
+        const char = pattern[i];
+        const next = pattern[i + 1];
+        if (char === '*' && next === '*') {
+            source += '.*';
+            i += 1;
+            continue;
+        }
+        if (char === '*') {
+            source += '[^/]*';
+            continue;
+        }
+        if (char === '?') {
+            source += '[^/]';
+            continue;
+        }
+        source += char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${source}$`);
+}
+export function changeDir(changeName) {
+    return path.posix.join('openspec', 'changes', changeName);
+}
+export function archiveDir(stamp, changeName) {
+    return path.posix.join('openspec', 'archive', `${stamp}-${changeName}`);
+}
+export const OPENSPEC_DIR = 'openspec';
+export const OPSX_DIR = '.opsx';
+export const CONFIG_FILES = ['config.yaml', 'config.yml'];
+//# sourceMappingURL=paths.js.map

package/dist/shared/pkg.d.ts

@@ -0,0 +1,3 @@
+/** 定位本包根目录（含 package.json；优先带 skills/ 的那一层）。 */
+export declare function packageRoot(): string;
+//# sourceMappingURL=pkg.d.ts.map

package/dist/shared/pkg.js

@@ -0,0 +1,23 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** 定位本包根目录（含 package.json；优先带 skills/ 的那一层）。 */
+export function packageRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    let fallback = null;
+    for (let i = 0; i < 8; i += 1) {
+        if (existsSync(path.join(dir, 'package.json'))) {
+            fallback = dir;
+            if (existsSync(path.join(dir, 'skills')) || existsSync(path.join(dir, 'presets')))
+                return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (fallback)
+        return fallback;
+    throw new Error('无法定位 OpenSpec 包根目录');
+}
+//# sourceMappingURL=pkg.js.map

package/dist/shared/version.d.ts

@@ -0,0 +1,9 @@
+export declare const VERSION: string;
+export declare const PACKAGE_NAME: string;
+/**
+ * 比较 major.minor.patch 版本；预发布后缀（-rc 等）低于同号正式版。
+ * 任一侧无法解析时返回 null，调用方按「版本未知」处理，不当作满足要求。
+ */
+export declare function compareVersions(a: string, b: string): number | null;
+export declare function shortHash(value: string): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/shared/version.js

@@ -0,0 +1,34 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { packageRoot } from './pkg.js';
+import path from 'node:path';
+const pkg = JSON.parse(readFileSync(path.join(packageRoot(), 'package.json'), 'utf8'));
+export const VERSION = pkg.version;
+export const PACKAGE_NAME = pkg.name;
+/**
+ * 比较 major.minor.patch 版本；预发布后缀（-rc 等）低于同号正式版。
+ * 任一侧无法解析时返回 null，调用方按「版本未知」处理，不当作满足要求。
+ */
+export function compareVersions(a, b) {
+    const parse = (value) => /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value.trim());
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return null;
+    for (let index = 1; index <= 3; index += 1) {
+        const diff = Number(left[index]) - Number(right[index]);
+        if (diff !== 0)
+            return Math.sign(diff);
+    }
+    if (left[4] === right[4])
+        return 0;
+    if (left[4] === undefined)
+        return 1;
+    if (right[4] === undefined)
+        return -1;
+    return left[4] < right[4] ? -1 : 1;
+}
+export function shortHash(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 12);
+}
+//# sourceMappingURL=version.js.map

package/dist/usage/analyze.d.ts

@@ -0,0 +1,5 @@
+import type { UsageOptions, UsageReport } from './types.js';
+export { sumTokens } from './parse.js';
+export declare function analyzeUsage(options: UsageOptions): UsageReport;
+export declare function renderUsageMarkdown(report: UsageReport): string;
+//# sourceMappingURL=analyze.d.ts.map