@lmzhen/dsh-evolution-merge 0.0.0 → 0.29.0

package/lib/types/scan-ports.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compose the channel and authoring flow into ScanPorts for a scan run.
+ *
+ * Approval off: round1 keeps the child, round2 authors the staging tree, then commits.
+ * Approval on: round1 disposes the child immediately; the row waits in pending and the later
+ * approve run must open a new child (not handled by this factory).
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { SkillCard } from './skill-card.ts';
+import { type ConversationChannelLike } from './channel-port.ts';
+import type { CommitPort } from './commit-execute.ts';
+import type { StageToolContext } from './stage-tool.ts';
+import type { ScanPorts } from './scan-run.ts';
+export interface CreateScanPortsOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runId: string;
+    readonly cards: readonly SkillCard[];
+    readonly screening: ScanPorts['screening'];
+    readonly channel: ConversationChannelLike;
+    readonly parent: unknown;
+    readonly allow: readonly string[];
+    readonly cwd?: string;
+    readonly timeoutMs: number;
+    readonly approval: boolean;
+    readonly commitPort: CommitPort;
+    readonly now: () => number;
+    readonly onChild?: (context: StageToolContext) => void;
+    readonly onChildClosed?: (childId: string) => void;
+}
+export declare function createChannelScanPorts(options: CreateScanPortsOptions): ScanPorts;
+//# sourceMappingURL=scan-ports.d.ts.map

package/lib/types/scan-run.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The scan pair loop. Registry/report lifecycle stays in withMergeRun; this module owns
+ * candidate → round1 → pending/fuse → commit transitions and returns the report draft.
+ */
+import { type MergeCandidate, type MergeDecision, type MergeFailure, type MergeRow } from './contracts.ts';
+import type { EvolutionIoLike, RunStage } from '@lmzhen/dsh-evolution-core';
+import type { MergeRunReportDraft } from './run-shell.ts';
+export interface ScanRound1Outcome {
+    readonly kind: 'keep' | 'merge' | 'failed';
+    readonly decision?: MergeDecision;
+    readonly failure?: MergeFailure;
+    readonly stagingRef?: string;
+    readonly stagingExpiresAt?: number;
+}
+export interface ScanRound2Outcome {
+    readonly kind: 'merged' | 'failed';
+    readonly unitId?: string;
+    readonly archived?: readonly string[];
+    readonly target?: {
+        readonly requested: string;
+        readonly actual: string;
+        readonly created: boolean;
+    };
+    readonly failure?: MergeFailure;
+}
+export interface ScanPorts {
+    screening(signal: AbortSignal): Promise<readonly MergeCandidate[]>;
+    round1(candidate: MergeCandidate, signal: AbortSignal): Promise<ScanRound1Outcome>;
+    round2(row: MergeRow, decision: MergeDecision, signal: AbortSignal): Promise<ScanRound2Outcome>;
+}
+export interface RunScanOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly now: () => number;
+    readonly signal: AbortSignal;
+    readonly approval: boolean;
+    readonly timeoutMinutes?: number;
+    readonly startedAt?: number;
+    readonly ports: ScanPorts;
+    readonly stage?: (stage: RunStage, progress?: {
+        done: number;
+        total: number;
+    }) => Promise<void>;
+}
+export declare function runScan(options: RunScanOptions): Promise<MergeRunReportDraft>;
+//# sourceMappingURL=scan-run.d.ts.map

package/lib/types/skill-card.d.ts

@@ -0,0 +1,12 @@
+export interface SkillCard {
+    readonly name: string;
+    readonly description: string;
+    readonly body: string;
+    readonly files?: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly protectedBy?: string | null;
+    readonly protectionUnknown?: boolean;
+}
+//# sourceMappingURL=skill-card.d.ts.map

package/lib/types/skipped.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Skipped filtering: a pair the operator marked as not-worth-merging stays out of automatic
+ * screening until mergeSkippedTtlDays expires. Explicit /merge pair ignores this set.
+ */
+import { type MergeRow } from './contracts.ts';
+export declare function skippedPairKeys(rows: readonly MergeRow[], ttlDays: number, now: number): ReadonlySet<string>;
+export declare function isSkippedPair(keys: ReadonlySet<string>, a: string, b: string): boolean;
+//# sourceMappingURL=skipped.d.ts.map

package/lib/types/stage-tool-registry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Child-scoped stage-tool bindings. A round child is bound only for the window in which its
+ * staging writes are legal; the tool resolves the caller from the platform exec and refuses
+ * when no binding exists.
+ */
+import type { StageToolContext } from './stage-tool.ts';
+export declare class StageToolRegistry {
+    private readonly bindings;
+    bind(childId: string, context: StageToolContext): void;
+    unbind(childId: string): void;
+    clear(): void;
+    resolve(exec: unknown): StageToolContext | undefined;
+}
+//# sourceMappingURL=stage-tool-registry.d.ts.map

package/lib/types/stage-tool.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The pure half of the model-facing merge_stage tool.
+ *
+ * Registration/session binding lives in the plugin shell; this function owns the rules a
+ * caller cannot bypass: only the bound merge child, and only the author phase may write.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type StageArea } from './staging-files.ts';
+export type StagePhase = 'decide' | 'author';
+export interface StageToolContext {
+    readonly runId: string;
+    readonly childId: string;
+    readonly expectedChildId: string;
+    readonly phase: StagePhase;
+}
+export type StageToolOp = {
+    readonly op: 'list';
+    readonly area: StageArea;
+    readonly path?: string;
+    readonly source?: string;
+} | {
+    readonly op: 'read';
+    readonly area: StageArea;
+    readonly path: string;
+    readonly source?: string;
+} | {
+    readonly op: 'write';
+    readonly path: string;
+    readonly content: string;
+} | {
+    readonly op: 'copy';
+    readonly source: string;
+    readonly from: string;
+    readonly to: string;
+};
+export type StageToolResult = {
+    readonly ok: true;
+    readonly value?: unknown;
+} | {
+    readonly ok: false;
+    readonly code: 'not-merge-child' | 'phase' | 'not-found' | 'io' | 'bad-path';
+    readonly message: string;
+};
+export declare function applyStageTool(io: EvolutionIoLike, home: string, ctx: StageToolContext, op: StageToolOp): Promise<StageToolResult>;
+//# sourceMappingURL=stage-tool.d.ts.map

package/lib/types/staged-tree.d.ts

@@ -0,0 +1,4 @@
+import { type EvolutionIoLike, type Probe } from '@lmzhen/dsh-evolution-core';
+import type { StagedTree } from './rules.ts';
+export declare function readStagedTree(io: EvolutionIoLike, home: string, runId: string): Promise<Probe<StagedTree>>;
+//# sourceMappingURL=staged-tree.d.ts.map

package/lib/types/staging-files.d.ts

@@ -0,0 +1,15 @@
+import { type EvolutionIoLike, type Probe } from '@lmzhen/dsh-evolution-core';
+export type StageArea = 'sources' | 'merged';
+export type StageWriteResult = {
+    readonly ok: true;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function writeStagedFile(io: EvolutionIoLike, home: string, runId: string, path: string, content: string, source?: string): Promise<StageWriteResult>;
+export declare function readStagedFile(io: EvolutionIoLike, home: string, runId: string, path: string, area: StageArea, source?: string): Promise<Probe<string>>;
+export declare function listStagedFiles(io: EvolutionIoLike, home: string, runId: string, area: StageArea, path?: string, source?: string): Promise<Probe<readonly string[]>>;
+/** Copy one source file into the merged target; the only cross-area operation allowed. */
+export declare function copyStagedFile(io: EvolutionIoLike, home: string, runId: string, source: string, from: string, to: string): Promise<StageWriteResult>;
+//# sourceMappingURL=staging-files.d.ts.map

package/lib/types/staging.d.ts

@@ -0,0 +1,49 @@
+import { type EvolutionIoLike, type Probe } from '@lmzhen/dsh-evolution-core';
+export declare const STAGING_SCHEMA_VERSION = 1;
+export declare function stageKeyOf(runId: string, pairKey: string): string;
+export declare function stagingRoot(home: string, runId: string): string;
+export interface StagingSource {
+    readonly name: string;
+    readonly body: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+}
+export interface StagingManifest {
+    readonly schemaVersion: typeof STAGING_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly target: string;
+    readonly mode?: 'merge-into-existing' | 'create-umbrella' | 'keep';
+    readonly sources: readonly string[];
+    readonly promptVersion: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+}
+export interface CreateStagingInput {
+    readonly runId: string;
+    readonly target: string;
+    readonly mode?: 'merge-into-existing' | 'create-umbrella' | 'keep';
+    readonly sources: readonly StagingSource[];
+    readonly promptVersion: string;
+    readonly ttlDays: number;
+    readonly now: () => number;
+}
+export type CreateStagingResult = {
+    readonly ok: true;
+    readonly path: string;
+    readonly manifest: StagingManifest;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function createStaging(io: EvolutionIoLike, home: string, input: CreateStagingInput): Promise<CreateStagingResult>;
+export interface StagedView {
+    readonly path: string;
+    readonly manifest: StagingManifest;
+}
+export declare function readStaging(io: EvolutionIoLike, home: string, runId: string): Promise<Probe<StagedView>>;
+export declare function ensureStaging(io: EvolutionIoLike, home: string, input: CreateStagingInput): Promise<CreateStagingResult>;
+export declare function setStagingTarget(io: EvolutionIoLike, home: string, stageKey: string, target: string, mode?: 'merge-into-existing' | 'create-umbrella' | 'keep'): Promise<boolean>;
+export declare function dropStaging(io: EvolutionIoLike, home: string, stageKey: string): Promise<void>;
+//# sourceMappingURL=staging.d.ts.map

package/lib/types/state.d.ts

@@ -0,0 +1,29 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type MergePairState, type MergeQueue, type MergeRow, type MergeState } from './contracts.ts';
+export declare function mergeStatePath(home: string): string;
+export interface LoadMergeStateResult {
+    readonly ok: boolean;
+    readonly state: MergeState;
+    readonly note?: string;
+}
+/** Pure read: never writes, never deletes a row. */
+export declare function loadMergeState(io: EvolutionIoLike, home: string): Promise<LoadMergeStateResult>;
+/** The ONE write point. The callback returns the whole row set, not a delta. */
+export declare function mutateMergeState<T>(io: EvolutionIoLike, home: string, now: () => number, fn: (rows: readonly MergeRow[]) => {
+    rows: readonly MergeRow[];
+    result: T;
+}): Promise<T>;
+export interface MoveRowPatch {
+    readonly queue: MergeQueue;
+    readonly state?: MergePairState;
+    readonly failure?: MergeRow['failure'];
+    readonly runId?: string;
+    readonly unitId?: string;
+    readonly origin?: MergeRow['origin'];
+    readonly attempts?: number;
+}
+export declare function upsertRow(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow): Promise<void>;
+export declare function moveRow(io: EvolutionIoLike, home: string, now: () => number, id: string, patch: MoveRowPatch): Promise<MergeRow | undefined>;
+export declare function dropRow(io: EvolutionIoLike, home: string, now: () => number, id: string): Promise<boolean>;
+export declare function rowsOf(io: EvolutionIoLike, home: string, queue?: MergeQueue): Promise<readonly MergeRow[]>;
+//# sourceMappingURL=state.d.ts.map

package/lib/types/status.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read-only status projections for the merge command/panel. Pure formatting over rows; no
+ * writes, no report reads. The UI and command parser share this vocabulary.
+ */
+import type { MergeQueue, MergeRow } from './contracts.ts';
+export interface MergeCounts {
+    readonly pending: number;
+    readonly retry: number;
+    readonly skipped: number;
+}
+export declare function countRows(rows: readonly MergeRow[]): MergeCounts;
+export declare function formatStatus(rows: readonly MergeRow[]): string;
+export declare function formatQueue(rows: readonly MergeRow[], queue: MergeQueue): string;
+//# sourceMappingURL=status.d.ts.map

package/lib/types/supersede.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A tree restore invalidates earlier merge runs: their commit receipts may describe a tree
+ * that no longer exists. Mark every non-superseded merge run in this process's registry.
+ */
+import type { RunRecord, RunRegistry } from '@lmzhen/dsh-evolution-core';
+export declare function mergeRunIdsToSupersede(runs: readonly RunRecord[]): readonly string[];
+export declare function supersedeMergeRuns(registry: RunRegistry): Promise<number>;
+//# sourceMappingURL=supersede.d.ts.map

package/lib/types/undo-merge.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Execute a merge undo from its commit receipt. The receipt names the unit and archived
+ * sources; this module resolves versions, plans the cross-skill undo and runs the shared
+ * executor. No command/routing logic here.
+ */
+import type { SkillVersion } from '@lmzhen/dsh-evolution-core';
+import { type UnitUndoExecution, type UnitUndoSink } from '@lmzhen/dsh-evolution-core';
+import type { CommitReceipt } from './commit-receipt.ts';
+export interface MergeUndoPort extends UnitUndoSink {
+    listVersions(skill: string): Promise<readonly SkillVersion[]>;
+}
+export declare function undoMergeReceipt(receipt: CommitReceipt, port: MergeUndoPort): Promise<UnitUndoExecution>;
+//# sourceMappingURL=undo-merge.d.ts.map

package/package.json

@@ -1,11 +1,39 @@
 {
   "name": "@lmzhen/dsh-evolution-merge",
-  "version": "0.0.0",
-  "description": "Placeholder for the skill merge host package; the release is published from CI.",
-  "license": "MIT",
+  "description": "Skill auto-merge domain: screening, two-round authoring, queues and commit orchestration (community build)",
+  "version": "0.29.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lmzhen/dsh-evolution.git",
     "directory": "packages/evolution-merge"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@lmzhen/dsh-evolution-core": "^0.29.0",
+    "@lmzhen/dsh-evolution-merge-engine": "^0.29.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5"
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.1 <0.2.2-0"
   }
 }