@alpsckr/unitycli 0.4.0

package/dist/extensions/tool-manifest.js

@@ -0,0 +1,53 @@
+import { BUILTIN_EXTENSION_MANIFESTS } from "./.generated-registry-data.js";
+/** 从 dotted tool name 推导 discovery group。 */
+export function groupFromToolName(name) {
+    const [group] = name.split(".");
+    return group || "tools";
+}
+/** 读取 extension tool 的真实包依赖；显式 requiresPackages 优先，否则回退到 extension-level 依赖。 */
+export function requiredPackagesForContribution(manifest, contribution) {
+    if (contribution.requiresPackages !== undefined) {
+        return [...new Set(contribution.requiresPackages)].sort();
+    }
+    return [...new Set(manifest.unityPackages.map((pkg) => pkg.packageId))].sort();
+}
+/** 汇总所有 built-in extension manifests 贡献的 tool 名单。 */
+export function builtinExtensionToolContributions() {
+    return BUILTIN_EXTENSION_MANIFESTS.flatMap((manifest) => (manifest.contributions.tools ?? []).map((contribution) => ({
+        extensionId: manifest.id,
+        extensionName: manifest.name,
+        manifest,
+        contribution,
+        name: contribution.name,
+        group: groupFromToolName(contribution.name),
+        requiresPackages: requiredPackagesForContribution(manifest, contribution)
+    })));
+}
+/** 查找某个 extension tool 的 manifest 贡献信息。 */
+export function findBuiltinExtensionToolContribution(name) {
+    return builtinExtensionToolContributions().find((tool) => tool.name === name);
+}
+/** 汇总 extension 级 group 视图，供离线 group discovery 使用。 */
+export function builtinExtensionToolGroups() {
+    const groups = new Map();
+    for (const tool of builtinExtensionToolContributions()) {
+        const existing = groups.get(tool.group);
+        if (existing) {
+            existing.toolCount += 1;
+            continue;
+        }
+        groups.set(tool.group, {
+            extensionId: tool.extensionId,
+            extensionName: tool.extensionName,
+            manifest: tool.manifest,
+            group: tool.group,
+            toolCount: 1
+        });
+    }
+    return [...groups.values()].sort((left, right) => left.group.localeCompare(right.group));
+}
+/** 读取所有 extension group 名称集合。 */
+export function builtinExtensionGroupNames() {
+    return builtinExtensionToolGroups().map((group) => group.group);
+}
+//# sourceMappingURL=tool-manifest.js.map

package/dist/extensions/tool-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-manifest.js","sourceRoot":"","sources":["../../src/extensions/tool-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAqB5E,6CAA6C;AAC7C,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,KAAK,IAAI,OAAO,CAAC;AAC1B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,+BAA+B,CAC7C,QAA2B,EAC3B,YAAuC;IAEvC,IAAI,YAAY,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QAChD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACjF,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,iCAAiC;IAC/C,OAAO,2BAA2B,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CACtD,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC1D,WAAW,EAAE,QAAQ,CAAC,EAAE;QACxB,aAAa,EAAE,QAAQ,CAAC,IAAI;QAC5B,QAAQ;QACR,YAAY;QACZ,IAAI,EAAE,YAAY,CAAC,IAAI;QACvB,KAAK,EAAE,iBAAiB,CAAC,YAAY,CAAC,IAAI,CAAC;QAC3C,gBAAgB,EAAE,+BAA+B,CAAC,QAAQ,EAAE,YAAY,CAAC;KAC1E,CAAC,CAAC,CACJ,CAAC;AACJ,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,oCAAoC,CAAC,IAAY;IAC/D,OAAO,iCAAiC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAChF,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,0BAA0B;IACxC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAqC,CAAC;IAC5D,KAAK,MAAM,IAAI,IAAI,iCAAiC,EAAE,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,SAAS,IAAI,CAAC,CAAC;YACxB,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,CAAC;SACb,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,0BAA0B;IACxC,OAAO,0BAA0B,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC"}

package/dist/extensions/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Extension system types for the UnityCLI.
+ *
+ * Defines the manifest schema, registry types, and descriptor loader types
+ * for the extension package system.
+ *
+ * Extensions are optional packages that contribute capabilities (tools,
+ * bridge commands, context descriptors, docs fragments) to the CLI without
+ * being compile-time dependencies of the core package.
+ */
+/** Unique extension identifier, e.g. "probuilder", "vfx-graph", "cinemachine". */
+export type ExtensionId = string;
+/** Status of an extension's availability in a given project. */
+export type ExtensionAvailability = "available" | "unavailable" | "unknown";
+/** A single required Unity package and its resolved state. */
+export interface UnityPackageRequirement {
+    /** Unity package identifier, e.g. "com.unity.probuilder". */
+    packageId: string;
+    /** 精确 SemVer 约束；省略表示接受任意已安装版本。 */
+    versionRange?: string;
+    /** Human-readable name for the package, e.g. "ProBuilder". */
+    displayName: string;
+}
+/** A tool capability ID contributed by an extension. Full AI-facing metadata lives in extension tool metadata. */
+export interface ExtensionToolContribution {
+    /** Tool name (dotted), e.g. "probuilder.create-shape". */
+    name: string;
+    /** Unity packages required by this specific tool; omitted means the extension-level package gate applies. */
+    requiresPackages?: string[];
+}
+/** A C# implementation entry contributed by an extension. */
+export interface ExtensionCSharpEntry {
+    /** Fully-qualified C# type name, e.g. "UnityCli.ProBuilderCommands". */
+    type: string;
+    /** Method name within the type. */
+    method?: string;
+    /** Description of the entry point. */
+    description: string;
+}
+/** All contributions an extension can make to the CLI system. */
+export interface ExtensionContributions {
+    /** Tool descriptors contributed by this extension. */
+    tools?: ExtensionToolContribution[];
+    /** C# implementation entry points. */
+    csharpEntries?: ExtensionCSharpEntry[];
+}
+/** 投影到 Packages/com.alpsckr.unitycli/Extensions/<id> 的 Unity 侧文件布局。 */
+export interface ExtensionUnityInstallLayout {
+    /** 布局标识；"directory" 表示以独立子目录安装。 */
+    layout?: "directory";
+    /** 相对 extensions/<id>/ 的源码路径，会复制到 Unity 扩展目录。 */
+    include?: string[];
+}
+/** The top-level extension manifest. */
+export interface ExtensionManifest {
+    /** Unique extension identifier (kebab-case), e.g. "probuilder". */
+    id: ExtensionId;
+    /** Human-readable extension name. */
+    name: string;
+    /** One-paragraph description of the extension. */
+    description: string;
+    /** Extension version (semver). */
+    version: string;
+    /** Required Unity packages for this extension to be available. */
+    unityPackages: UnityPackageRequirement[];
+    /** Capabilities contributed by this extension. */
+    contributions: ExtensionContributions;
+    /** Unity 侧扩展目录安装布局。 */
+    unityInstall?: ExtensionUnityInstallLayout;
+    /** Tags for categorization, e.g. ["modeling", "3d"]. */
+    tags?: string[];
+    /** Homepage or documentation URL. */
+    homepage?: string;
+}
+/** Resolved state of a single Unity package within a project. */
+export interface PackageResolution {
+    /** Whether the package is present in the project's manifest/lock. */
+    installed: boolean;
+    /** Resolved version, if installed. */
+    version?: string;
+}
+/** Resolved availability of an extension against a specific project. */
+export interface ExtensionAvailabilityResult {
+    /** The extension ID. */
+    extensionId: ExtensionId;
+    /** Overall availability status. */
+    status: ExtensionAvailability;
+    /** Per-package resolution details. */
+    packages: Array<PackageResolution & {
+        packageId: string;
+        displayName: string;
+    }>;
+    /** Missing package IDs (empty when status is "available"). */
+    missingPackageIds: string[];
+    /** Suggested next actions when status is "unavailable". */
+    nextActions: string[];
+}
+/** An extension entry in the registry, combining manifest + resolved state. */
+export interface RegistryExtension {
+    /** The extension manifest. */
+    manifest: ExtensionManifest;
+    /** Whether this extension has built-in bridge domain support in the CLI. */
+    hasBuiltinBridgeDomain: boolean;
+}
+/** A loaded extension descriptor with resolved availability. */
+export interface LoadedExtensionDescriptor {
+    /** The extension manifest. */
+    manifest: ExtensionManifest;
+    /** Resolved availability against a project. */
+    availability: ExtensionAvailabilityResult;
+    /** Tool descriptors contributed by this extension. */
+    tools: ExtensionToolContribution[];
+    /** C# implementation entries. */
+    csharpEntries: ExtensionCSharpEntry[];
+}

package/dist/extensions/types.js

@@ -0,0 +1,12 @@
+/**
+ * Extension system types for the UnityCLI.
+ *
+ * Defines the manifest schema, registry types, and descriptor loader types
+ * for the extension package system.
+ *
+ * Extensions are optional packages that contribute capabilities (tools,
+ * bridge commands, context descriptors, docs fragments) to the CLI without
+ * being compile-time dependencies of the core package.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/extensions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/extensions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/instances.d.ts

@@ -0,0 +1,163 @@
+import type { CliResult } from "./types.js";
+import { type ProjectIdentity } from "./project-identity.js";
+export declare const HEALTH_CHECK_TIMEOUT_MS = 300;
+export declare const HEALTH_CACHE_TTL_MS = 1000;
+export declare const MAIN_THREAD_PULSE_FRESH_MS = 2000;
+export type UnityInstanceStatus = "ready" | "transitioning" | "blocked" | "unresponsive" | "unverifiable" | "offline" | "conflict";
+export type InstanceTarget = "editor" | "runtime";
+export type RegistryLifecycle = "ready" | "transitioning" | "blocked" | "domain-reloading" | "compiling" | "importing" | "building" | "playmode-changing";
+export interface RegistryIdentity {
+    instanceId: string;
+    canonicalProjectPath: string;
+    displayProjectPath: string;
+}
+export interface RegistryEndpoint {
+    host: "127.0.0.1";
+    preferredPort: number;
+    actualPort: number;
+    fallback: boolean;
+    url: string;
+}
+export interface RegistryListener {
+    listenerId: string;
+    generation: number;
+    startedAt: string;
+    endpoint: RegistryEndpoint;
+}
+export interface RegistrySession {
+    target: InstanceTarget;
+    sessionId: string;
+    editorSessionId?: string;
+    runtimeSessionId?: string;
+    processId: number;
+    processStartedAt: string;
+    publishedAt: string;
+    publicationSequence: number;
+    lifecycle: RegistryLifecycle;
+    lastUnitySnapshot: Record<string, unknown>;
+    listener: RegistryListener;
+    progress: Array<Record<string, unknown>>;
+    blockers: Array<Record<string, unknown>>;
+    unityVersion?: string;
+    buildStamp?: string;
+    toolCatalogFingerprint?: string;
+    executablePath?: string;
+    buildId?: string;
+}
+export interface InstanceRegistryV3 {
+    version: 3;
+    revision: number;
+    canonicalizationVersion: 1;
+    identity: RegistryIdentity;
+    sessions: RegistrySession[];
+    publishedAt: string;
+}
+export interface UnityInstance {
+    instanceId: string;
+    canonicalizationVersion: 1;
+    canonicalProjectPath: string;
+    displayProjectPath: string;
+    projectPath: string;
+    projectName: string;
+    status: UnityInstanceStatus;
+    target?: InstanceTarget;
+    revision: number;
+    updatedAt: string;
+    sessions: RegistrySession[];
+    activeSession?: RegistrySession;
+    allSessions: RegistrySession[];
+    sessionId?: string;
+    editorSessionId?: string;
+    runtimeSessionId?: string;
+    processId?: number;
+    publishedAt?: string;
+    lastUnitySnapshot?: Record<string, unknown>;
+    progress: Array<Record<string, unknown>>;
+    blockers: Array<Record<string, unknown>>;
+    unityVersion?: string;
+    buildStamp?: string;
+    toolCatalogFingerprint?: string;
+    claimVerification: "verified" | "unverifiable" | "none";
+    processClaimIds?: number[];
+}
+export interface ProjectProcessClaimInspection {
+    verification: "verified" | "unverifiable" | "unsupported";
+    processIds: number[];
+    processClaims?: Array<{
+        processId: number;
+        processStartedAt: string;
+    }>;
+}
+export interface InstanceSelection {
+    instance: UnityInstance;
+    matchedBy: "alias" | "instanceId" | "projectPath" | "cwd";
+}
+export interface InstanceRegistryReadResult {
+    instances: UnityInstance[];
+    invalidRecordCount: number;
+}
+/** journal 等本地 mutation 在 acceptance 前只读取v3 registry identity，不依赖CWD推断。 */
+export interface InstanceJournalIdentity {
+    instanceId: string;
+    canonicalProjectPath: string;
+}
+interface ProcessObservation {
+    processId: number;
+    processStartedAt?: string;
+    executablePath?: string;
+    state: "alive" | "dead" | "unverifiable";
+}
+export type SessionProcessVerification = "verified" | "dead" | "unverifiable";
+export declare class InstanceRegistryError extends Error {
+    readonly code: string;
+    readonly nextActions: string[];
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, nextActions?: string[], details?: Record<string, unknown> | undefined);
+}
+/** 清空仅成功 health identity 的短缓存；失败探测从不缓存。 */
+export declare function clearInstanceHealthCache(): void;
+/** 顶层 instances 控制面只读 registry；prune 由 C# writer 的 PID/start-time reducer 完成。 */
+export declare function handleInstancesCommand(command: string | undefined, flags: Record<string, string | boolean>, dataDir: string, requestId: string): Promise<CliResult>;
+/** 顶层 target 只保留 canonical project identity alias 管理。 */
+export declare function handleTargetCommand(command: string | undefined, positional: string[], flags: Record<string, string | boolean>, dataDir: string, requestId: string): Promise<CliResult>;
+/** 离线 project constraint/discovery 使用 canonical identity，不依赖 active target 或单实例 fallback。 */
+export declare function currentInstanceProjectPath(flags: Record<string, string | boolean>, dataDir: string, cwd?: string): Promise<string | undefined>;
+/** 严格 selector：完整 ID/path/alias，或 CWD 中最近 Unity project root。 */
+export declare function selectInstanceForFlags(flags: Record<string, string | boolean>, dataDir: string, cwd?: string, target?: InstanceTarget): Promise<InstanceSelection>;
+export declare function selectObservationInstanceForFlags(flags: Record<string, string | boolean>, dataDir: string, remainingMs?: number, cwd?: string, target?: InstanceTarget): Promise<InstanceSelection>;
+/**
+ * durable root 在 domain reload 中读取 journal 时不能依赖瞬时 /health ready。
+ * 该 selector 要求唯一 Registry claim 的 PID、process start 与 Unity.exe 成立；可正向归因的命令行 claim 不能与其冲突。
+ */
+export declare function selectTransitionInstanceForFlags(flags: Record<string, string | boolean>, dataDir: string, remainingMs: number, cwd?: string, target?: InstanceTarget): Promise<InstanceSelection>;
+/** 即时观察只归约原始 registry：不得发 health 请求或扫描旧 PID。 */
+export declare function reduceObservationRegistryRecord(record: InstanceRegistryV3, observations?: Map<number, ProcessObservation>, target?: InstanceTarget): UnityInstance;
+/**
+ * fallback 前重新证明 registry claim 对应原 PID/start 的 Unity.exe。
+ * 命令行存在 -projectPath 时必须匹配 canonical identity；正式 Hub/普通启动可以不携带该参数。
+ */
+export declare function verifyRegistrySessionProcess(identity: RegistryIdentity, session: RegistrySession, timeoutMs?: number): Promise<SessionProcessVerification>;
+/** 将显式 --instance 解析为已验证的 Registry v3 canonical identity，供本地 journal 绑定请求。 */
+export declare function resolveInstanceJournalIdentity(flags: Record<string, string | boolean>, dataDir: string): Promise<InstanceJournalIdentity | undefined>;
+export declare function hasInstanceForFlags(flags: Record<string, string | boolean>, dataDir: string, cwd?: string): Promise<boolean>;
+/** 将 identity/registry 失败保留为稳定 CLI envelope。 */
+export declare function instanceSelectionFailure(requestId: string, error: unknown): CliResult | undefined;
+export declare function instancesDir(dataDir?: string): string;
+export declare function aliasesV2Path(dataDir?: string): string;
+/** 只读全部合法v3 identity records；单个坏文件不能污染其他canonical project。 */
+export declare function readInstances(dataDir?: string, now?: number, target?: InstanceTarget | "all"): Promise<UnityInstance[]>;
+/** 控制面可读取无效数量；具体文件名、路径和内容始终保持私有。 */
+export declare function readInstancesWithRegistryDiagnostics(dataDir?: string, now?: number, target?: InstanceTarget | "all"): Promise<InstanceRegistryReadResult>;
+/** CanonicalPath v1 补充进程观察；只返回可由显式 -projectPath 正向归因的 claim。 */
+export declare function inspectProjectProcessClaims(identity: RegistryIdentity | ProjectIdentity, timeoutMs?: number): Promise<ProjectProcessClaimInspection>;
+/** 将 OS 进程 claim 与 registry session 交叉验证；冲突时清除任何可执行 session 选择。 */
+export declare function applyProjectProcessClaimInspection(instance: UnityInstance, inspection: ProjectProcessClaimInspection): UnityInstance;
+/** 纯 reducer 可由测试注入 OS observations，禁止 TS 回写观察结果。 */
+export declare function reduceRegistryRecord(record: InstanceRegistryV3, observations: Map<number, ProcessObservation>, now?: number, target?: InstanceTarget | "all"): Promise<UnityInstance>;
+/** public summary 不包含 endpoint、port 或 listener generation；null/空字段不输出以控制上下文。 */
+export declare function instanceListSummary(instance: UnityInstance): Record<string, unknown>;
+/** 返回 doctor 应报告但产品不得解析的旧本地状态文件。 */
+export declare function obsoleteLocalStatePaths(dataDir: string): Promise<string[]>;
+/** 批量读取 PID start time；access denied 保留 unverifiable claim 并 fail closed。 */
+export declare function probeProcessObservations(processIds: number[], timeoutMs?: number): Promise<Map<number, ProcessObservation>>;
+export {};