@tomflow/proflow-task-migration-runner 0.1.1 → 0.1.3

package/CONFIGURATION.md

@@ -0,0 +1,23 @@
+# task-migration-runner configuration
+
+Canonical public config: `.proflow/config/task-migration-runner.json`
+
+This file is Workspace-owned data. `platform uninstall` does not delete it. Values are JSON strings. Raw secrets must not be stored here; `secretRef` fields contain opaque references only.
+
+## Fields
+
+| Key | Type | Required | Sensitive | Source | Meaning |
+|---|---|---:|---:|---|---|
+| `databasePath` | `path` | yes | no | User or owning Module supplies an absolute/local path that exists on this Workspace. | Task SQLite database path |
+
+## Materialize
+
+Create or update the canonical JSON object at:
+
+`.proflow/config/task-migration-runner.json`
+
+Use only declared keys and string values. Do not create a second Platform configuration database.
+
+## Base completion check
+
+Run `platform modules`. This Module should no longer report required keys in `missingConfig`. `platform start` performs the authoritative Module-owned validation before starting anything.

package/dist/deployment/adapter.d.ts

@@ -1,67 +1,343 @@
+export declare function createBehaviorAdapter(config?: Record<string, string>): {
+    describe: () => {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    };
+    preflight: () => {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    };
+    status: () => {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    };
+    verify: () => {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "FAILED";
+            error: {
+                code: "APPLY_FAILED" | "VERIFY_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    };
+    doctor: () => {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "BLOCKED";
+            error: {
+                code: "VERIFY_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+            data?: {} | null;
+        };
+        observedEffects: never[];
+    };
+    migrate: () => {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "FAILED";
+            error: {
+                code: "APPLY_FAILED" | "VERIFY_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: string[];
+    };
+};
 export declare const behaviorAdapter: {
-    readonly describe: () => {
+    describe: () => {
         result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "task-migration-runner";
-            readonly moduleVersion: "0.1.1";
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
         };
         observedEffects: never[];
     };
-    readonly preflight: () => {
+    preflight: () => {
         result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "task-migration-runner";
-            readonly moduleVersion: "0.1.1";
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data?: {} | null;
+            checks?: unknown[];
         };
         observedEffects: never[];
     };
-    readonly status: () => {
+    status: () => {
         result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "task-migration-runner";
-            readonly moduleVersion: "0.1.1";
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
         };
         observedEffects: never[];
     };
-    readonly verify: () => {
+    verify: () => {
         result: {
             contract: "deployment.result.v1";
-            ok: true;
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
             status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        } | {
+            contract: "deployment.result.v1";
             moduleRef: "task-migration-runner";
-            moduleVersion: "0.1.1";
-            checks: {
-                id: string;
-                status: string;
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "FAILED";
+            error: {
+                code: "APPLY_FAILED" | "VERIFY_FAILED";
                 message: string;
-            }[];
+                retryable: boolean;
+            };
+            data?: {} | null;
+            checks?: unknown[];
         };
         observedEffects: never[];
     };
-    readonly doctor: () => {
+    doctor: () => {
         result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "task-migration-runner";
-            readonly moduleVersion: "0.1.1";
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "BLOCKED";
+            error: {
+                code: "VERIFY_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+            data?: {} | null;
         };
         observedEffects: never[];
     };
-    readonly migrate: () => {
+    migrate: () => {
         result: {
-            readonly contract: "deployment.result.v1";
-            readonly ok: true;
-            readonly status: "SUCCEEDED";
-            readonly moduleRef: "task-migration-runner";
-            readonly moduleVersion: "0.1.1";
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+            data?: {} | null;
+            checks?: unknown[];
+        };
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "SUCCEEDED";
+            data?: {} | null;
+            checks?: unknown[];
+        } | {
+            contract: "deployment.result.v1";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.3";
+            ok: boolean;
+            status: "FAILED";
+            error: {
+                code: "APPLY_FAILED" | "VERIFY_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+            data?: {} | null;
+            checks?: unknown[];
         };
         observedEffects: string[];
     };
 };
+export declare function createProductionBinding(input: {
+    config: Record<string, string>;
+}): {
+    behaviorAdapter: Record<string, unknown>;
+};

package/dist/deployment/adapter.js

@@ -1,31 +1,147 @@
+import { observeDeclaredModuleStatus } from "@tomflow/proflow-module-contract";
+import { taskMigrations } from "@tomflow/proflow-task-store-sqlite/migrations";
+import { applyMigrations, getMigrationStatus, verifyMigrations, } from "../src/index.js";
 import { descriptor } from "./descriptor.js";
-const result = {
+const base = {
     contract: "deployment.result.v1",
-    ok: true,
-    status: "SUCCEEDED",
     moduleRef: descriptor.moduleRef,
     moduleVersion: descriptor.moduleVersion,
 };
-export const behaviorAdapter = {
-    describe: () => ({ result, observedEffects: [] }),
-    preflight: () => ({ result, observedEffects: [] }),
-    status: () => ({ result, observedEffects: [] }),
-    verify: () => ({
-        result: {
-            ...result,
-            checks: [
-                {
+const success = (data, checks) => ({
+    ...base,
+    ok: true,
+    status: "SUCCEEDED",
+    ...(data === undefined ? {} : { data }),
+    ...(checks === undefined ? {} : { checks }),
+});
+const actionRequired = (description, data, checks) => ({
+    ...base,
+    ok: false,
+    status: "ACTION_REQUIRED",
+    actionRequired: { action: "configure-task-migrations", description },
+    ...(data === undefined ? {} : { data }),
+    ...(checks === undefined ? {} : { checks }),
+});
+const failed = (message, data, checks, code = "APPLY_FAILED") => ({
+    ...base,
+    ok: false,
+    status: "FAILED",
+    error: { code, message, retryable: false },
+    ...(data === undefined ? {} : { data }),
+    ...(checks === undefined ? {} : { checks }),
+});
+const blocked = (message, data) => ({
+    ...base,
+    ok: false,
+    status: "BLOCKED",
+    error: { code: "VERIFY_FAILED", message, retryable: true },
+    ...(data === undefined ? {} : { data }),
+});
+function migrationInput(config) {
+    const databasePath = config.databasePath;
+    if (!databasePath)
+        return undefined;
+    return { databasePath, migrations: taskMigrations };
+}
+function statusData(config) {
+    const input = migrationInput(config);
+    if (input === undefined)
+        return undefined;
+    const status = getMigrationStatus(input);
+    const verification = verifyMigrations(input);
+    return {
+        migrated: verification.ok,
+        appliedVersions: status.appliedVersions,
+        pendingVersions: status.pendingVersions,
+        metadataDrift: status.metadataDrift,
+        checksumDrift: status.checksumDrift,
+        legacyMetadataVersions: status.legacyMetadataVersions,
+        missingTables: status.missingTables,
+        schemaDrift: status.schemaDrift,
+    };
+}
+export function createBehaviorAdapter(config = {}) {
+    return {
+        describe: () => ({ result: success(), observedEffects: [] }),
+        preflight: () => ({
+            result: migrationInput(config) === undefined
+                ? actionRequired("databasePath is required for Task migrations")
+                : success(),
+            observedEffects: [],
+        }),
+        status: () => ({
+            result: success(observeDeclaredModuleStatus(descriptor, config, "STOPPED")),
+            observedEffects: [],
+        }),
+        verify: () => {
+            const input = migrationInput(config);
+            if (input === undefined) {
+                const check = {
                     id: "migration-state-pass",
-                    status: "PASS",
-                    message: "Migration verification primitive is available",
-                },
-            ],
+                    status: "FAIL",
+                    message: "databasePath is required for Task migration verification",
+                };
+                return {
+                    result: actionRequired(check.message, undefined, [check]),
+                    observedEffects: [],
+                };
+            }
+            const verification = verifyMigrations(input);
+            const data = statusData(config);
+            const check = {
+                id: "migration-state-pass",
+                status: verification.ok ? "PASS" : "FAIL",
+                message: verification.ok
+                    ? "Task migration state and SQLite integrity match the current schema"
+                    : (verification.error?.message ??
+                        "Task migration verification failed"),
+            };
+            return {
+                result: verification.ok
+                    ? success(data, [check])
+                    : failed(check.message, data, [check], "VERIFY_FAILED"),
+                observedEffects: [],
+            };
         },
-        observedEffects: [],
-    }),
-    doctor: () => ({ result, observedEffects: [] }),
-    migrate: () => ({
-        result,
-        observedEffects: ["Applies Task Store migration SQL to SQLite"],
-    }),
-};
+        doctor: () => {
+            const data = statusData(config);
+            if (data === undefined) {
+                return {
+                    result: actionRequired("databasePath is required for Task migration diagnostics"),
+                    observedEffects: [],
+                };
+            }
+            return {
+                result: data.migrated
+                    ? success(data)
+                    : blocked("Task migration state requires a repair/migration plan before readiness", data),
+                observedEffects: [],
+            };
+        },
+        migrate: () => {
+            const input = migrationInput(config);
+            if (input === undefined) {
+                return {
+                    result: actionRequired("databasePath is required before Task migrations can run"),
+                    observedEffects: [],
+                };
+            }
+            const migration = applyMigrations(input);
+            return {
+                result: migration.ok
+                    ? success({ applied: migration.applied, pending: migration.pending })
+                    : failed(migration.error?.message ?? "Task migration failed", {
+                        applied: migration.applied,
+                        pending: migration.pending,
+                    }),
+                observedEffects: migration.ok
+                    ? ["Applies Task Store migration SQL to SQLite"]
+                    : [],
+            };
+        },
+    };
+}
+export const behaviorAdapter = createBehaviorAdapter();
+export function createProductionBinding(input) {
+    return { behaviorAdapter: createBehaviorAdapter(input.config) };
+}

package/dist/deployment/descriptor.d.ts

@@ -3,11 +3,10 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "task-migration-runner";
     readonly packageName: "@tomflow/proflow-task-migration-runner";
-    readonly moduleVersion: "0.1.1";
+    readonly moduleVersion: "0.1.3";
     readonly kind: "cli";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";
-    readonly installClass: "core";
     readonly identity: {
         readonly domain: "task-orchestration";
         readonly summary: "Deterministically discovers, applies and verifies Task Store SQLite schema migrations.";
@@ -44,5 +43,9 @@ export declare const descriptor: {
         readonly id: "overview";
         readonly path: "./README.md";
         readonly description: "Package-owned module overview";
+    }, {
+        readonly id: "configuration";
+        readonly path: "./CONFIGURATION.md";
+        readonly description: "Module configuration fields, sources and materialization instructions";
     }];
 };

package/dist/deployment/descriptor.js

@@ -3,11 +3,10 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "task-migration-runner",
     packageName: "@tomflow/proflow-task-migration-runner",
-    moduleVersion: "0.1.1",
+    moduleVersion: "0.1.3",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",
-    installClass: "core",
     identity: {
         domain: "task-orchestration",
         summary: "Deterministically discovers, applies and verifies Task Store SQLite schema migrations.",
@@ -15,7 +14,11 @@ export const descriptor = {
     provides: [],
     requires: [],
     requirements: [
-        { kind: "runtime", runtime: "node", versionRange: ">=24.19.0" },
+        {
+            kind: "runtime",
+            runtime: "node",
+            versionRange: ">=24.19.0",
+        },
     ],
     configSlots: [
         {
@@ -57,5 +60,10 @@ export const descriptor = {
             path: "./README.md",
             description: "Package-owned module overview",
         },
+        {
+            id: "configuration",
+            path: "./CONFIGURATION.md",
+            description: "Module configuration fields, sources and materialization instructions",
+        },
     ],
 };

package/dist/src/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { runCli } from "./index.js";
 export { runCli } from "./index.js";
 if (process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(process.argv[1]).href) {
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
     const output = await runCli(process.argv.slice(2));
     process.stdout.write(`${output}\n`);
     if (JSON.parse(output).ok !== true)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-task-migration-runner",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -12,19 +12,18 @@
     "./deployment/descriptor": "./dist/deployment/descriptor.js"
   },
   "bin": {
-    "proflow-task-migrate": "./dist/src/cli.js",
-    "proflow-task-migration-runner": "./self-install.mjs"
+    "proflow-task-migrate": "./dist/src/cli.js"
   },
   "files": [
     "dist",
     "proflow.module.json",
     "conformance.json",
     "README.md",
-    "self-install.mjs"
+    "CONFIGURATION.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-task-store-sqlite": "^0.1.1",
-    "@tomflow/proflow-module-contract": "^0.1.1"
+    "@tomflow/proflow-task-store-sqlite": "^0.1.3",
+    "@tomflow/proflow-module-contract": "^0.1.2"
   },
   "description": "Deterministically discovers, applies and verifies Task Store SQLite schema migrations.",
   "keywords": [
@@ -34,11 +33,6 @@
   ],
   "proflow": {
     "module": true,
-    "installClass": "core",
-    "installRequires": [
-      "@tomflow/proflow-module-contract",
-      "@tomflow/proflow-task-store-sqlite"
-    ],
     "descriptor": "./dist/deployment/descriptor.js",
     "manifest": "./proflow.module.json"
   },

package/proflow.module.json

@@ -3,11 +3,10 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "task-migration-runner",
 	"packageName": "@tomflow/proflow-task-migration-runner",
-	"moduleVersion": "0.1.1",
+	"moduleVersion": "0.1.3",
 	"kind": "cli",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",
-	"installClass": "core",
 	"identity": {
 		"domain": "task-orchestration",
 		"summary": "Deterministically discovers, applies and verifies Task Store SQLite schema migrations."
@@ -60,6 +59,11 @@
 			"id": "overview",
 			"path": "./README.md",
 			"description": "Package-owned module overview"
+		},
+		{
+			"id": "configuration",
+			"path": "./CONFIGURATION.md",
+			"description": "Module configuration fields, sources and materialization instructions"
 		}
 	]
 }

package/CHANGELOG.md

@@ -1,7 +0,0 @@
-# @tomflow/proflow-task-migration-runner
-
-## 0.1.1
-
-### Patch Changes
-
-- Close the Real-1 global Platform control-plane contract across every published ProFlow package. Platform CLI now owns one durable global Workspace binding with canonical identity, cross-process operation locking, cwd/`--workspace` install targeting, cross-directory instance commands, whole-instance uninstall/rebind, and deterministic npm/yarn/pnpm Workspace package-manager selection. Every package-owned install entry, including newly generated Module Template packages, delegates to the Shell-global `platform` command and fails closed when that global CLI is unavailable; Deployment Conformance and the formal test plans mechanically enforce the same rule across all 24 packages.

package/self-install.mjs

@@ -1,34 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-
-const [command, ...rest] = process.argv.slice(2);
-const usage = "Usage: npx @tomflow/proflow-task-migration-runner install\n";
-if (command === "--help" || command === "-h") {
-	process.stdout.write(usage);
-	process.exit(0);
-}
-if (command !== "install" || rest.length > 0) {
-	process.stderr.write(usage);
-	process.exit(2);
-}
-const executable = process.platform === "win32" ? "platform.cmd" : "platform";
-const result = spawnSync(
-	executable,
-	[
-		"install",
-		"@tomflow/proflow-task-migration-runner",
-		"--workspace",
-		process.cwd(),
-	],
-	{ cwd: process.cwd(), env: process.env, stdio: "inherit" },
-);
-if (result.error) {
-	if (result.error.code === "ENOENT") {
-		process.stderr.write(
-			"GLOBAL_PLATFORM_CLI_REQUIRED: install @tomflow/proflow-platform-cli globally before package-owned install\n",
-		);
-		process.exit(127);
-	}
-	throw result.error;
-}
-process.exit(result.status ?? 1);