@shrkcrft/migrate 0.1.0-alpha.10

package/dist/engine/define-migration.d.ts

@@ -0,0 +1,8 @@
+import { type IMigration } from '../schema/migration.js';
+/**
+ * Type-safe builder for migration definitions. Validates basic shape
+ * (no empty id / title / steps); deeper validation happens at plan /
+ * apply time when the steps are evaluated.
+ */
+export declare function defineMigration(input: Omit<IMigration, 'schema'>): IMigration;
+//# sourceMappingURL=define-migration.d.ts.map

package/dist/engine/define-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-migration.d.ts","sourceRoot":"","sources":["../../src/engine/define-migration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAE3E;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,GAAG,UAAU,CAO7E"}

package/dist/engine/define-migration.js

@@ -0,0 +1,16 @@
+import { MIGRATION_SCHEMA } from "../schema/migration.js";
+/**
+ * Type-safe builder for migration definitions. Validates basic shape
+ * (no empty id / title / steps); deeper validation happens at plan /
+ * apply time when the steps are evaluated.
+ */
+export function defineMigration(input) {
+    if (!input.id)
+        throw new Error('defineMigration: id is required');
+    if (!input.title)
+        throw new Error('defineMigration: title is required');
+    if (!input.steps || input.steps.length === 0) {
+        throw new Error('defineMigration: steps must be non-empty');
+    }
+    return { schema: MIGRATION_SCHEMA, ...input };
+}

package/dist/engine/plan-migration.d.ts

@@ -0,0 +1,32 @@
+import { type IRewritePlan } from '@shrkcrft/structural-search';
+import type { IMigration, MigrationStep } from '../schema/migration.js';
+export interface IPlannedStep {
+    index: number;
+    id: string;
+    description?: string;
+    step: MigrationStep;
+    /** For structural-rewrite steps, the computed plan (dry). */
+    rewritePlan?: IRewritePlan;
+}
+export interface IMigrationPlan {
+    schema: 'sharkcraft.migration-plan/v1';
+    migration: {
+        id: string;
+        title: string;
+    };
+    plannedSteps: readonly IPlannedStep[];
+    /** Sum of (rewritePlan.totalEdits) across all rewrite steps. */
+    totalEdits: number;
+    /** Sum of (rewritePlan.files.length) across all rewrite steps. */
+    totalFiles: number;
+}
+/**
+ * Compute the migration's plan without writing anything.
+ *
+ * `structural-rewrite` steps are pre-computed via `planRewrite` so the
+ * caller can preview file-level edits before deciding to apply.
+ * `shell` / `check` steps are listed as-is — they're executed only
+ * during `applyMigration`.
+ */
+export declare function planMigration(migration: IMigration, projectRoot: string): IMigrationPlan;
+//# sourceMappingURL=plan-migration.d.ts.map

package/dist/engine/plan-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-migration.d.ts","sourceRoot":"","sources":["../../src/engine/plan-migration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAExE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,8BAA8B,CAAC;IACvC,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,YAAY,EAAE,SAAS,YAAY,EAAE,CAAC;IACtC,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAsCxF"}

package/dist/engine/plan-migration.js

@@ -0,0 +1,49 @@
+import { planRewrite } from '@shrkcrft/structural-search';
+/**
+ * Compute the migration's plan without writing anything.
+ *
+ * `structural-rewrite` steps are pre-computed via `planRewrite` so the
+ * caller can preview file-level edits before deciding to apply.
+ * `shell` / `check` steps are listed as-is — they're executed only
+ * during `applyMigration`.
+ */
+export function planMigration(migration, projectRoot) {
+    const plannedSteps = [];
+    let totalEdits = 0;
+    let totalFiles = 0;
+    for (let i = 0; i < migration.steps.length; i += 1) {
+        const step = migration.steps[i];
+        const id = step.id ?? `step-${i + 1}`;
+        if (step.kind === 'structural-rewrite') {
+            const rewritePlan = planRewrite({
+                projectRoot,
+                pattern: step.pattern,
+                recipe: step.recipe,
+            });
+            totalEdits += rewritePlan.totalEdits;
+            totalFiles += rewritePlan.files.length;
+            plannedSteps.push({
+                index: i,
+                id,
+                ...(step.description ? { description: step.description } : {}),
+                step,
+                rewritePlan,
+            });
+        }
+        else {
+            plannedSteps.push({
+                index: i,
+                id,
+                ...(step.description ? { description: step.description } : {}),
+                step,
+            });
+        }
+    }
+    return {
+        schema: 'sharkcraft.migration-plan/v1',
+        migration: { id: migration.id, title: migration.title },
+        plannedSteps,
+        totalEdits,
+        totalFiles,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './schema/migration.js';
+export * from './engine/define-migration.js';
+export * from './engine/plan-migration.js';
+export * from './runner/apply-migration.js';
+export * from './runner/state-store.js';
+export * from './runner/resume-migration.js';
+export * from './runner/prune-migrations.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./schema/migration.js";
+export * from "./engine/define-migration.js";
+export * from "./engine/plan-migration.js";
+export * from "./runner/apply-migration.js";
+export * from "./runner/state-store.js";
+export * from "./runner/resume-migration.js";
+export * from "./runner/prune-migrations.js";

package/dist/runner/apply-migration.d.ts

@@ -0,0 +1,37 @@
+import { type IMigration, type IMigrationRunReport, type IStepRunResult } from '../schema/migration.js';
+export interface IApplyMigrationOptions {
+    projectRoot: string;
+    /** When true, structural rewrites compute but don't write. Shell and
+     * check steps are still skipped (not executed). Default false. */
+    dryRun?: boolean;
+    /** When true, the runner stops at the first failed step. Default true. */
+    stopOnFailure?: boolean;
+    /** Per-shell timeout in ms. Default 5 * 60 * 1000. */
+    shellTimeoutMs?: number;
+    /**
+     * When true, persist a checkpoint after each step (and the final
+     * report) to `.sharkcraft/migrations/<id>.state.json` so
+     * `resumeMigration` can pick up where `apply` left off. Default true
+     * for non-dry-run, false for dry-run.
+     */
+    persistCheckpoints?: boolean;
+    /**
+     * Index of the step to start at. Steps before this index are
+     * carried over from `priorSteps` with status `applied`. Used by
+     * `resumeMigration`; callers don't typically set this directly.
+     */
+    resumeFromIndex?: number;
+    /** Step results carried over from a prior run (when resuming). */
+    priorSteps?: readonly IStepRunResult[];
+}
+/**
+ * Execute a migration end-to-end. Returns a structured run report;
+ * never throws (errors are captured in per-step `status: 'failed'`).
+ *
+ * `structural-rewrite` steps go through `planRewrite` + `applyRewritePlan`
+ * (or stop at plan when `dryRun: true`). `shell` / `check` steps run
+ * via `spawnSync(bash -c, ...)`. A `check` step that exits non-zero
+ * marks the step as `failed` and (by default) halts the run.
+ */
+export declare function applyMigration(migration: IMigration, options: IApplyMigrationOptions): IMigrationRunReport;
+//# sourceMappingURL=apply-migration.d.ts.map

package/dist/runner/apply-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-migration.d.ts","sourceRoot":"","sources":["../../src/runner/apply-migration.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAGhC,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB;sEACkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,sBAAsB,GAC9B,mBAAmB,CAqIrB"}

package/dist/runner/apply-migration.js

@@ -0,0 +1,169 @@
+import { spawnSync } from 'node:child_process';
+import * as nodePath from 'node:path';
+import { applyRewritePlan, planRewrite } from '@shrkcrft/structural-search';
+import { MIGRATION_RUN_SCHEMA, } from "../schema/migration.js";
+import { MigrationStateStore } from "./state-store.js";
+/**
+ * Execute a migration end-to-end. Returns a structured run report;
+ * never throws (errors are captured in per-step `status: 'failed'`).
+ *
+ * `structural-rewrite` steps go through `planRewrite` + `applyRewritePlan`
+ * (or stop at plan when `dryRun: true`). `shell` / `check` steps run
+ * via `spawnSync(bash -c, ...)`. A `check` step that exits non-zero
+ * marks the step as `failed` and (by default) halts the run.
+ */
+export function applyMigration(migration, options) {
+    const startedAt = new Date().toISOString();
+    const start = Date.now();
+    const dryRun = options.dryRun ?? false;
+    const stopOnFailure = options.stopOnFailure ?? true;
+    const shellTimeoutMs = options.shellTimeoutMs ?? 5 * 60 * 1000;
+    const persist = options.persistCheckpoints ?? !dryRun;
+    const resumeFromIndex = options.resumeFromIndex ?? 0;
+    const priorSteps = options.priorSteps ?? [];
+    const store = persist ? new MigrationStateStore(options.projectRoot) : undefined;
+    const results = [];
+    let halted = false;
+    // Carry forward prior successful steps when resuming.
+    if (resumeFromIndex > 0 && priorSteps.length > 0) {
+        for (const p of priorSteps) {
+            if (p.index >= resumeFromIndex)
+                break;
+            // Re-stamp status as `applied` (in case the prior run halted
+            // BEFORE this step's status was updated — shouldn't happen with
+            // checkpoints but be defensive).
+            results.push(p.status === 'applied' || p.status === 'planned' || p.status === 'skipped'
+                ? p
+                : { ...p, status: 'applied' });
+        }
+    }
+    for (let i = resumeFromIndex; i < migration.steps.length; i += 1) {
+        const step = migration.steps[i];
+        const id = step.id ?? `step-${i + 1}`;
+        if (halted) {
+            results.push({
+                index: i,
+                id,
+                kind: step.kind,
+                status: 'skipped',
+                message: 'skipped after previous failure',
+                durationMs: 0,
+                diagnostics: [],
+            });
+            continue;
+        }
+        const stepStart = Date.now();
+        if (step.kind === 'structural-rewrite') {
+            const plan = planRewrite({
+                projectRoot: options.projectRoot,
+                pattern: step.pattern,
+                recipe: step.recipe,
+            });
+            const apply = applyRewritePlan(plan, { projectRoot: options.projectRoot, dryRun });
+            const failed = apply.conflicts.length > 0;
+            results.push({
+                index: i,
+                id,
+                kind: step.kind,
+                status: failed ? 'failed' : (dryRun ? 'planned' : 'applied'),
+                message: failed
+                    ? `${apply.conflicts.length} conflict(s) — file content drifted`
+                    : `${apply.filesChanged} file(s) ${dryRun ? 'would be ' : ''}changed, ${plan.totalEdits} edit(s)`,
+                durationMs: Date.now() - stepStart,
+                rewriteStats: {
+                    filesScanned: plan.filesScanned,
+                    filesAttempted: apply.filesAttempted,
+                    filesChanged: apply.filesChanged,
+                    totalEdits: plan.totalEdits,
+                    conflicts: apply.conflicts,
+                },
+                diagnostics: [...plan.diagnostics, ...apply.diagnostics],
+            });
+            if (failed && stopOnFailure)
+                halted = true;
+        }
+        else if (step.kind === 'shell' || step.kind === 'check') {
+            if (dryRun) {
+                results.push({
+                    index: i,
+                    id,
+                    kind: step.kind,
+                    status: 'planned',
+                    message: `${step.kind} (dry-run): ${step.command}`,
+                    durationMs: Date.now() - stepStart,
+                    diagnostics: [],
+                });
+                continue;
+            }
+            const cwd = step.cwd
+                ? nodePath.resolve(options.projectRoot, step.cwd)
+                : options.projectRoot;
+            const res = spawnSync('bash', ['-c', step.command], {
+                cwd,
+                encoding: 'utf8',
+                timeout: shellTimeoutMs,
+            });
+            const exitCode = res.status ?? -1;
+            const failed = exitCode !== 0;
+            results.push({
+                index: i,
+                id,
+                kind: step.kind,
+                status: failed ? 'failed' : 'applied',
+                message: failed
+                    ? `exit ${exitCode}: ${oneLine(res.stderr ?? '') || step.command}`
+                    : `exit 0: ${step.command}`,
+                durationMs: Date.now() - stepStart,
+                shellOutput: {
+                    exitCode,
+                    stdout: (res.stdout ?? '').slice(0, 8000),
+                    stderr: (res.stderr ?? '').slice(0, 8000),
+                },
+                diagnostics: [],
+            });
+            if (step.kind === 'check' && failed && stopOnFailure)
+                halted = true;
+        }
+        if (store) {
+            // Per-step checkpoint so a crashing runner / killed process can
+            // still be resumed from the right point.
+            store.write(migration.id, buildPartialReport(migration, dryRun, startedAt, start, results));
+        }
+    }
+    const overall = results.some((r) => r.status === 'failed')
+        ? 'fail'
+        : results.some((r) => r.status === 'applied' || r.status === 'planned')
+            ? 'pass'
+            : 'skipped';
+    const report = {
+        schema: MIGRATION_RUN_SCHEMA,
+        migration: { id: migration.id, title: migration.title },
+        dryRun,
+        startedAt,
+        totalDurationMs: Date.now() - start,
+        overall,
+        steps: results,
+    };
+    if (store)
+        store.write(migration.id, report);
+    return report;
+}
+function oneLine(s) {
+    return s.replace(/\s+/g, ' ').trim().slice(0, 160);
+}
+function buildPartialReport(migration, dryRun, startedAt, start, results) {
+    const overall = results.some((r) => r.status === 'failed')
+        ? 'fail'
+        : results.some((r) => r.status === 'applied' || r.status === 'planned')
+            ? 'pass'
+            : 'skipped';
+    return {
+        schema: MIGRATION_RUN_SCHEMA,
+        migration: { id: migration.id, title: migration.title },
+        dryRun,
+        startedAt,
+        totalDurationMs: Date.now() - start,
+        overall,
+        steps: results,
+    };
+}

package/dist/runner/prune-migrations.d.ts

@@ -0,0 +1,43 @@
+export interface IPruneOptions {
+    projectRoot: string;
+    /** Minimum age in days for a state file to be eligible. Default 30. */
+    olderThanDays?: number;
+    /**
+     * When true, also prune state files where the last recorded run is
+     * a `fail`. Default false — failed migrations are typically what the
+     * user wants to keep so they can `resume`.
+     */
+    includeFailed?: boolean;
+    /** When true, list what would be deleted but don't touch disk. */
+    dryRun?: boolean;
+}
+export interface IPrunedEntry {
+    id: string;
+    startedAt: string;
+    overall: 'pass' | 'fail' | 'skipped';
+    ageDays: number;
+    reason: 'older-than' | 'failed-included';
+}
+export interface IPruneResult {
+    schema: 'sharkcraft.migration-prune/v1';
+    /** Total state files scanned. */
+    scanned: number;
+    /** Files matching the eligibility criteria. */
+    eligible: number;
+    /** Files actually removed (0 in dry-run). */
+    removed: number;
+    dryRun: boolean;
+    entries: readonly IPrunedEntry[];
+    diagnostics: readonly string[];
+}
+/**
+ * Prune `.sharkcraft/migrations/*.state.json` files older than
+ * `olderThanDays`. Used to keep the dashboard's Migrations panel
+ * focused on recent activity.
+ *
+ * By default skips `overall: 'fail'` entries — those are kept so the
+ * user can `shrk migrate resume`. Pass `includeFailed: true` to clear
+ * those too (typical after a project-wide cleanup).
+ */
+export declare function pruneMigrations(options: IPruneOptions): IPruneResult;
+//# sourceMappingURL=prune-migrations.d.ts.map

package/dist/runner/prune-migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune-migrations.d.ts","sourceRoot":"","sources":["../../src/runner/prune-migrations.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,GAAG,iBAAiB,CAAC;CAC1C;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,+BAA+B,CAAC;IACxC,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CA4FpE"}

package/dist/runner/prune-migrations.js

@@ -0,0 +1,115 @@
+import { existsSync, readdirSync, rmSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { MigrationStateStore } from "./state-store.js";
+/**
+ * Prune `.sharkcraft/migrations/*.state.json` files older than
+ * `olderThanDays`. Used to keep the dashboard's Migrations panel
+ * focused on recent activity.
+ *
+ * By default skips `overall: 'fail'` entries — those are kept so the
+ * user can `shrk migrate resume`. Pass `includeFailed: true` to clear
+ * those too (typical after a project-wide cleanup).
+ */
+export function pruneMigrations(options) {
+    const olderThanDays = options.olderThanDays ?? 30;
+    const includeFailed = options.includeFailed ?? false;
+    const dryRun = options.dryRun ?? false;
+    const diagnostics = [];
+    const dir = nodePath.join(options.projectRoot, '.sharkcraft', 'migrations');
+    if (!existsSync(dir)) {
+        return {
+            schema: 'sharkcraft.migration-prune/v1',
+            scanned: 0,
+            eligible: 0,
+            removed: 0,
+            dryRun,
+            entries: [],
+            diagnostics: ['no .sharkcraft/migrations/ directory'],
+        };
+    }
+    const store = new MigrationStateStore(options.projectRoot);
+    const now = Date.now();
+    let scanned = 0;
+    const eligibleEntries = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (e) {
+        diagnostics.push(`readdir failed: ${e.message}`);
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.state.json'))
+            continue;
+        scanned += 1;
+        const abs = nodePath.join(dir, entry);
+        let report;
+        try {
+            report = store.read(entry.replace(/\.state\.json$/, ''));
+        }
+        catch {
+            report = undefined;
+        }
+        let startedAt;
+        let ageMs;
+        if (report) {
+            startedAt = report.startedAt;
+            ageMs = now - Date.parse(report.startedAt);
+        }
+        else {
+            // Corrupted state file — fall back to mtime.
+            try {
+                const st = statSync(abs);
+                startedAt = new Date(st.mtimeMs).toISOString();
+                ageMs = now - st.mtimeMs;
+            }
+            catch {
+                diagnostics.push(`could not stat ${abs}`);
+                continue;
+            }
+        }
+        if (Number.isNaN(ageMs))
+            continue;
+        const ageDays = ageMs / (1000 * 60 * 60 * 24);
+        const isFailed = report?.overall === 'fail';
+        let reason;
+        if (ageDays >= olderThanDays) {
+            if (isFailed && !includeFailed)
+                continue;
+            reason = ageDays >= olderThanDays ? 'older-than' : undefined;
+            if (isFailed && includeFailed)
+                reason = 'failed-included';
+        }
+        if (!reason)
+            continue;
+        eligibleEntries.push({
+            id: report?.migration.id ?? entry.replace(/\.state\.json$/, ''),
+            startedAt,
+            overall: report?.overall ?? 'skipped',
+            ageDays: Math.floor(ageDays * 10) / 10,
+            reason,
+        });
+    }
+    let removed = 0;
+    if (!dryRun) {
+        for (const e of eligibleEntries) {
+            try {
+                rmSync(nodePath.join(dir, `${e.id}.state.json`));
+                removed += 1;
+            }
+            catch (err) {
+                diagnostics.push(`rm failed for ${e.id}: ${err.message}`);
+            }
+        }
+    }
+    return {
+        schema: 'sharkcraft.migration-prune/v1',
+        scanned,
+        eligible: eligibleEntries.length,
+        removed,
+        dryRun,
+        entries: eligibleEntries,
+        diagnostics,
+    };
+}

package/dist/runner/resume-migration.d.ts

@@ -0,0 +1,28 @@
+import type { IMigration, IMigrationRunReport } from '../schema/migration.js';
+export interface IResumeMigrationOptions {
+    projectRoot: string;
+    /** Forwarded to applyMigration. */
+    dryRun?: boolean;
+    stopOnFailure?: boolean;
+    shellTimeoutMs?: number;
+}
+export interface IResumeMigrationResult {
+    /** Final run report after the resume. */
+    report: IMigrationRunReport;
+    /** Step index the resume started at. */
+    resumedFromIndex: number;
+    /** Free-form diagnostics about the resume decision. */
+    diagnostics: readonly string[];
+}
+/**
+ * Pick up a previously-failed migration from the step that failed and
+ * continue forward. Reads the saved state at
+ * `.sharkcraft/migrations/<id>.state.json` (written by `applyMigration`
+ * after each step) and dispatches a fresh `applyMigration` call with
+ * `resumeFromIndex` set.
+ *
+ * Returns a diagnostic and skips re-running when no resume point is
+ * found (everything already applied, or no saved state at all).
+ */
+export declare function resumeMigration(migration: IMigration, options: IResumeMigrationOptions): IResumeMigrationResult;
+//# sourceMappingURL=resume-migration.d.ts.map

package/dist/runner/resume-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-migration.d.ts","sourceRoot":"","sources":["../../src/runner/resume-migration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,uBAAuB,GAC/B,sBAAsB,CAqBxB"}

package/dist/runner/resume-migration.js

@@ -0,0 +1,42 @@
+import { applyMigration } from "./apply-migration.js";
+import { findResumePoint, MigrationStateStore } from "./state-store.js";
+/**
+ * Pick up a previously-failed migration from the step that failed and
+ * continue forward. Reads the saved state at
+ * `.sharkcraft/migrations/<id>.state.json` (written by `applyMigration`
+ * after each step) and dispatches a fresh `applyMigration` call with
+ * `resumeFromIndex` set.
+ *
+ * Returns a diagnostic and skips re-running when no resume point is
+ * found (everything already applied, or no saved state at all).
+ */
+export function resumeMigration(migration, options) {
+    const diagnostics = [];
+    const store = new MigrationStateStore(options.projectRoot);
+    const prior = store.read(migration.id);
+    if (!prior) {
+        diagnostics.push(`no saved state for migration "${migration.id}" — running from the beginning.`);
+        const fresh = applyMigration(migration, applyOpts(options));
+        return { report: fresh, resumedFromIndex: 0, diagnostics };
+    }
+    const resumePoint = findResumePoint(prior);
+    if (resumePoint === undefined) {
+        diagnostics.push(`migration "${migration.id}" already complete; nothing to resume.`);
+        return { report: prior, resumedFromIndex: prior.steps.length, diagnostics };
+    }
+    diagnostics.push(`resuming from step ${resumePoint + 1} (${migration.steps[resumePoint]?.id ?? 'unknown'}).`);
+    const report = applyMigration(migration, {
+        ...applyOpts(options),
+        resumeFromIndex: resumePoint,
+        priorSteps: prior.steps.slice(0, resumePoint),
+    });
+    return { report, resumedFromIndex: resumePoint, diagnostics };
+}
+function applyOpts(options) {
+    return {
+        projectRoot: options.projectRoot,
+        ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+        ...(options.stopOnFailure !== undefined ? { stopOnFailure: options.stopOnFailure } : {}),
+        ...(options.shellTimeoutMs !== undefined ? { shellTimeoutMs: options.shellTimeoutMs } : {}),
+    };
+}

package/dist/runner/state-store.d.ts

@@ -0,0 +1,26 @@
+import type { IMigrationRunReport } from '../schema/migration.js';
+/**
+ * Persist per-migration run state under `.sharkcraft/migrations/`. The
+ * checkpoint is the full `IMigrationRunReport` so far — `resumeMigration`
+ * reads it back, finds the last failed step, and continues from there.
+ */
+export declare class MigrationStateStore {
+    private readonly projectRoot;
+    readonly dir: string;
+    constructor(projectRoot: string);
+    pathFor(migrationId: string): string;
+    exists(migrationId: string): boolean;
+    read(migrationId: string): IMigrationRunReport | undefined;
+    write(migrationId: string, report: IMigrationRunReport): void;
+    clear(migrationId: string): void;
+}
+/**
+ * Find the index of the first step the resume runner should re-execute.
+ *
+ *   - First failed step → resume from there.
+ *   - No failures + steps remaining → resume from the first skipped /
+ *     pending step.
+ *   - All steps applied → undefined (nothing to resume).
+ */
+export declare function findResumePoint(report: IMigrationRunReport): number | undefined;
+//# sourceMappingURL=state-store.d.ts.map

package/dist/runner/state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/runner/state-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAIlE;;;;GAIG;AACH,qBAAa,mBAAmB;IAGlB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAFxC,SAAgB,GAAG,EAAE,MAAM,CAAC;gBAEC,WAAW,EAAE,MAAM;IAIhD,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAIpC,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIpC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAS1D,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAK7D,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;CAGjC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAQ/E"}

package/dist/runner/state-store.js

@@ -0,0 +1,59 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+const DIR = '.sharkcraft/migrations';
+/**
+ * Persist per-migration run state under `.sharkcraft/migrations/`. The
+ * checkpoint is the full `IMigrationRunReport` so far — `resumeMigration`
+ * reads it back, finds the last failed step, and continues from there.
+ */
+export class MigrationStateStore {
+    projectRoot;
+    dir;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.dir = nodePath.join(projectRoot, DIR);
+    }
+    pathFor(migrationId) {
+        return nodePath.join(this.dir, `${migrationId}.state.json`);
+    }
+    exists(migrationId) {
+        return existsSync(this.pathFor(migrationId));
+    }
+    read(migrationId) {
+        if (!this.exists(migrationId))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(this.pathFor(migrationId), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    write(migrationId, report) {
+        mkdirSync(this.dir, { recursive: true });
+        writeFileSync(this.pathFor(migrationId), JSON.stringify(report, null, 2), 'utf8');
+    }
+    clear(migrationId) {
+        if (this.exists(migrationId))
+            rmSync(this.pathFor(migrationId));
+    }
+}
+/**
+ * Find the index of the first step the resume runner should re-execute.
+ *
+ *   - First failed step → resume from there.
+ *   - No failures + steps remaining → resume from the first skipped /
+ *     pending step.
+ *   - All steps applied → undefined (nothing to resume).
+ */
+export function findResumePoint(report) {
+    for (const s of report.steps) {
+        if (s.status === 'failed')
+            return s.index;
+    }
+    for (const s of report.steps) {
+        if (s.status === 'skipped' || s.status === 'pending')
+            return s.index;
+    }
+    return undefined;
+}

package/dist/schema/migration.d.ts

@@ -0,0 +1,90 @@
+import type { RewriteRecipe, StructuralPattern } from '@shrkcrft/structural-search';
+export declare const MIGRATION_SCHEMA: "sharkcraft.migration/v1";
+export declare const MIGRATION_RUN_SCHEMA: "sharkcraft.migration-run/v1";
+/**
+ * Ordered list of steps. Each step is one of:
+ *
+ *   - `structural-rewrite`: pair of (pattern, recipe) consumed by
+ *     `@shrkcrft/structural-search`. The most common step kind.
+ *   - `shell`: a literal shell command. Useful for `bun install`,
+ *     `bun run build`, version bumps, etc.
+ *   - `check`: a CLI command whose exit code gates the migration.
+ *     Same as `shell` but the runner records a pass/fail per step.
+ */
+export type MigrationStep = {
+    kind: 'structural-rewrite';
+    id?: string;
+    description?: string;
+    pattern: StructuralPattern;
+    recipe: RewriteRecipe;
+} | {
+    kind: 'shell';
+    id?: string;
+    description?: string;
+    /** Shell command line. Run via bash -c. */
+    command: string;
+    /** Working directory relative to project root. */
+    cwd?: string;
+} | {
+    kind: 'check';
+    id?: string;
+    description?: string;
+    command: string;
+    cwd?: string;
+};
+export interface IMigration {
+    schema: typeof MIGRATION_SCHEMA;
+    /** Stable migration id (used to look it up on disk). */
+    id: string;
+    /** Display title. */
+    title: string;
+    /** Optional human description. */
+    description?: string;
+    /** Steps run in this order. */
+    steps: readonly MigrationStep[];
+}
+export type StepStatus = 'pending' | 'planned' | 'applied' | 'failed' | 'skipped';
+export interface IStepRunResult {
+    /** Index in the migration's steps array. */
+    index: number;
+    /** Step id (defaults to `step-<index>`). */
+    id: string;
+    kind: MigrationStep['kind'];
+    status: StepStatus;
+    /** Human-readable headline. */
+    message: string;
+    /** Wall-clock duration of the step, in ms. */
+    durationMs: number;
+    /** For structural-rewrite steps: counts of files / edits. */
+    rewriteStats?: {
+        filesScanned: number;
+        filesAttempted: number;
+        filesChanged: number;
+        totalEdits: number;
+        conflicts: readonly string[];
+    };
+    /** For shell / check steps: captured stdout + exit code. */
+    shellOutput?: {
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    };
+    /** Free-form diagnostics from the step. */
+    diagnostics: readonly string[];
+}
+export interface IMigrationRunReport {
+    schema: typeof MIGRATION_RUN_SCHEMA;
+    migration: {
+        id: string;
+        title: string;
+    };
+    /** True for the `plan` flow (no fs writes); false for `apply`. */
+    dryRun: boolean;
+    startedAt: string;
+    totalDurationMs: number;
+    /** Overall status: `pass` if every step is `applied` (or `skipped`);
+     * `fail` if any step failed. */
+    overall: 'pass' | 'fail' | 'skipped';
+    steps: readonly IStepRunResult[];
+}
+//# sourceMappingURL=migration.d.ts.map

package/dist/schema/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/schema/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEpF,eAAO,MAAM,gBAAgB,EAAG,yBAAkC,CAAC;AACnE,eAAO,MAAM,oBAAoB,EAAG,6BAAsC,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,oBAAoB,CAAC;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,aAAa,CAAC;CACvB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEN,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,OAAO,gBAAgB,CAAC;IAChC,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CACjC;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElF,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,YAAY,CAAC,EAAE;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;KAC9B,CAAC;IACF,4DAA4D;IAC5D,WAAW,CAAC,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,2CAA2C;IAC3C,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IACpC,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB;oCACgC;IAChC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;CAClC"}

package/dist/schema/migration.js

@@ -0,0 +1,2 @@
+export const MIGRATION_SCHEMA = 'sharkcraft.migration/v1';
+export const MIGRATION_RUN_SCHEMA = 'sharkcraft.migration-run/v1';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shrkcrft/migrate",
+  "version": "0.1.0-alpha.10",
+  "description": "SharkCraft migrations: orchestrate multi-step refactors (structural rewrites + shell + checkpoints) as one replayable migration. The safe path for big cross-cutting refactors.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sharkcraft/sharkcraft.git",
+    "directory": "packages/migrate"
+  },
+  "homepage": "https://github.com/sharkcraft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/sharkcraft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "migration",
+    "codemod",
+    "orchestration"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.10",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}