create-principles-disciple 1.130.3 → 1.131.1

package/console/dist/server/routes/update.js

@@ -10,6 +10,7 @@ import { migrateLegacyExtensionBackups, reservePdBackupDestination, resolvePdBac
 import { resolveExtensionsDir, resolveUpdateLayout, resolvePluginDir, readCurrentVersion, } from '../utils/installed-layout.js';
 import { ActivationCompatibilityReadModel } from '@principles/core/runtime-v2';
 import { collectFileDepLinkSpecs } from '../utils/update-links.js';
+import { updateMutationController, LEGACY_MUTATION_AUTHORITY, } from '../update/mutation-controller.js';
 /**
  * Legacy rule contract preflight (2026-08-19): refuse to swap the runtime
  * while an ACTIVE owner-approved rule still depends on a RuleHost contract
@@ -100,6 +101,40 @@ function logLegacyBackupMigration(source) {
 // ---------------------------------------------------------------------------
 // Core update operations (inline to avoid cross-package import)
 // ---------------------------------------------------------------------------
+/**
+ * Read the identity of a staged release package.
+ *
+ * Returns undefined when the file is missing, malformed, or when the package
+ * does not self-identify as principles-disciple with a valid semver version
+ * (rc-1/rc-2: unknown JSON is validated through guards, never a type
+ * assertion).
+ *
+ * Refusing an identity-less staged package BEFORE any production copy turns
+ * silent runtime corruption into a loud, structured error (rc-9). Regression
+ * from 2026-09-03: a stub tarball carrying only a fake version with no
+ * package name was copied into the real ~/.pd/runtime, which made the update
+ * page report a false "already latest" and blocked every future update. A
+ * real principles-disciple / create-principles-disciple tarball always
+ * carries name + valid semver.
+ */
+function readStagedPackageIdentity(pkgPath) {
+    try {
+        const raw = fs.readFileSync(pkgPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed))
+            return undefined;
+        if (parsed.name !== 'principles-disciple')
+            return undefined;
+        if (typeof parsed.version !== 'string' || semver.valid(parsed.version) === null)
+            return undefined;
+        return { name: parsed.name, version: parsed.version };
+    }
+    catch {
+        return undefined;
+    }
+}
+const STAGED_PACKAGE_REFUSAL_MESSAGE = 'Update source is not a valid principles-disciple release (package missing identity or valid version).';
+const STAGED_PACKAGE_REFUSAL_NEXT_ACTION = 'Try the update again later, or run the official installer (npx create-principles-disciple) to repair PD.';
 /**
  * Recursively copy a directory tree.
  *
@@ -495,6 +530,30 @@ async function doApplyUpdate(options, workspaceDir) {
         // not support GNU tar's --force-local, so relative path is the universal fix.
         execFileSync('tar', ['xzf', 'package.tgz', '--strip-components=1'], { cwd: tempDir, stdio: 'pipe' });
         fs.unlinkSync(tarballPath);
+        // 3.5 Staged-package identity guard (2026-09-03 regression): refuse a
+        // tarball that does not name itself principles-disciple with a valid
+        // version BEFORE any production byte is copied — the incident stub
+        // carried no name. A real release always carries both.
+        if (readStagedPackageIdentity(path.join(tempDir, 'package.json')) === undefined) {
+            if (fs.existsSync(tempDir))
+                fs.rmSync(tempDir, { recursive: true, force: true });
+            if (backupPath && fs.existsSync(backupPath))
+                fs.rmSync(backupPath, { recursive: true, force: true });
+            appendUpdateHistory(workspaceDir, {
+                fromVersion,
+                toVersion: toVersion ?? 'unknown',
+                success: false,
+                kind: 'refusal',
+                reason: 'staged_package_invalid',
+                nextAction: STAGED_PACKAGE_REFUSAL_NEXT_ACTION,
+            });
+            return {
+                success: false,
+                message: STAGED_PACKAGE_REFUSAL_MESSAGE,
+                reason: 'staged_package_invalid',
+                nextAction: STAGED_PACKAGE_REFUSAL_NEXT_ACTION,
+            };
+        }
         // 4. Compute diff and apply.
         // Fix 3: we ONLY apply modified + added files. We deliberately skip ALL
         // deletions — the tarball (principles-disciple) only contains dist/,
@@ -858,6 +917,29 @@ async function doInlineFullUpdate(workspaceDir) {
         // gateway is stopped or any production file is copied.
         const newPkgPath = path.join(tempDir, 'plugin', 'package.json');
         const stagedVersion = readCurrentVersion(path.join(tempDir, 'plugin'));
+        // Staged-package identity guard (2026-09-03 regression): the staged plugin
+        // must self-identify as principles-disciple with a valid version before
+        // the gateway is stopped or any production file is copied. The incident
+        // stub carried only a fake version with no package name.
+        if (readStagedPackageIdentity(path.join(tempDir, 'plugin', 'package.json')) === undefined) {
+            if (tempDir && fs.existsSync(tempDir))
+                fs.rmSync(tempDir, { recursive: true, force: true });
+            appendUpdateHistory(workspaceDir, {
+                fromVersion,
+                toVersion: stagedVersion ?? 'unknown',
+                success: false,
+                kind: 'refusal',
+                reason: 'staged_package_invalid',
+                nextAction: STAGED_PACKAGE_REFUSAL_NEXT_ACTION,
+            });
+            return {
+                success: false,
+                message: STAGED_PACKAGE_REFUSAL_MESSAGE,
+                reason: 'staged_package_invalid',
+                nextAction: STAGED_PACKAGE_REFUSAL_NEXT_ACTION,
+                requiresRestart: false,
+            };
+        }
         const progressed = fromVersion !== 'unknown' &&
             stagedVersion !== undefined &&
             semver.valid(fromVersion) !== null &&
@@ -1081,10 +1163,19 @@ async function doInlineFullUpdate(workspaceDir) {
 // ---------------------------------------------------------------------------
 // Route handler
 // ---------------------------------------------------------------------------
-export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
-    const pluginDir = resolvePluginDir(workspaceDir);
-    // GET /check
-    if (subPath === '/check') {
+/**
+ * PRI-659: the four mutation kinds below are the legacy console updater's
+ * implementations, registered into the MutationController (ADR-0023/0024
+ * migration boundary). handleUpdateRoute is now a thin dispatcher: it maps
+ * the URL subPath to a mutation kind and lets the controller resolve the
+ * authority. The implementation stays here verbatim (replace-then-delete —
+ * no third updater, no logic duplication); when ReleaseManager matures it
+ * registers under `release-manager` for the same kinds and this route layer
+ * needs no further change.
+ */
+function legacyCheckMutation(req, res, ctx) {
+    return (async () => {
+        const pluginDir = resolvePluginDir(ctx.workspaceDir);
         if (req.method !== 'GET') {
             sendMethodNotAllowed(res);
             return;
@@ -1111,10 +1202,11 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
         catch (err) {
             sendError(res, 500, 'update_check_error', err instanceof Error ? err.message : 'Unknown error');
         }
-        return;
-    }
-    // POST /apply
-    if (subPath === '/apply') {
+    })();
+}
+function legacyApplyMutation(req, res, ctx) {
+    return (async () => {
+        const pluginDir = resolvePluginDir(ctx.workspaceDir);
         if (req.method !== 'POST') {
             sendMethodNotAllowed(res);
             return;
@@ -1146,7 +1238,7 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
                 return;
             }
             // Path traversal validation
-            if (!validatePathInWorkspace(targetDir, workspaceDir)) {
+            if (!validatePathInWorkspace(targetDir, ctx.workspaceDir)) {
                 sendBadRequest(res, 'targetDir must be within workspace or extensions directory');
                 return;
             }
@@ -1154,7 +1246,7 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
                 targetDir,
                 mergeStrategy,
                 createBackup,
-            }, workspaceDir);
+            }, ctx.workspaceDir);
             sendSuccess(res, result);
         }
         catch (err) {
@@ -1164,10 +1256,11 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
             }
             sendError(res, 500, 'update_apply_error', err instanceof Error ? err.message : 'Unknown error');
         }
-        return;
-    }
-    // POST /rollback
-    if (subPath === '/rollback') {
+    })();
+}
+function legacyRollbackMutation(req, res, ctx) {
+    return (async () => {
+        const pluginDir = resolvePluginDir(ctx.workspaceDir);
         if (req.method !== 'POST') {
             sendMethodNotAllowed(res);
             return;
@@ -1189,15 +1282,15 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
                 return;
             }
             // Path traversal validation
-            if (!validatePathInWorkspace(targetDir, workspaceDir)) {
+            if (!validatePathInWorkspace(targetDir, ctx.workspaceDir)) {
                 sendBadRequest(res, 'targetDir must be within workspace or extensions directory');
                 return;
             }
-            if (!validatePathInWorkspace(backupDir, workspaceDir)) {
+            if (!validatePathInWorkspace(backupDir, ctx.workspaceDir)) {
                 sendBadRequest(res, 'backupDir must be within the workspace, extensions directory, or PD backups directory');
                 return;
             }
-            const result = await doRollbackUpdate({ targetDir, backupDir }, workspaceDir);
+            const result = await doRollbackUpdate({ targetDir, backupDir }, ctx.workspaceDir);
             sendSuccess(res, result);
         }
         catch (err) {
@@ -1207,22 +1300,42 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
             }
             sendError(res, 500, 'update_rollback_error', err instanceof Error ? err.message : 'Unknown error');
         }
-        return;
-    }
-    // POST /apply-full — inline tarball download + file copy (no external installer)
-    if (subPath === '/apply-full') {
+    })();
+}
+function legacyApplyFullMutation(req, res, ctx) {
+    return (async () => {
         if (req.method !== 'POST') {
             sendMethodNotAllowed(res);
             return;
         }
         try {
-            const result = await doInlineFullUpdate(workspaceDir);
+            const result = await doInlineFullUpdate(ctx.workspaceDir);
             sendSuccess(res, result);
         }
         catch (err) {
             sendError(res, 500, 'update_apply_full_error', err instanceof Error ? err.message : 'Unknown error');
         }
+    })();
+}
+// PRI-659: register the legacy authority (ADR-0024 D-1 fallback authority)
+// for every mutation kind. Registration is the ONLY coupling between this
+// implementation and the controller — no other module needs to know where
+// the legacy implementation lives.
+updateMutationController.register('check', { name: LEGACY_MUTATION_AUTHORITY, handler: legacyCheckMutation });
+updateMutationController.register('apply', { name: LEGACY_MUTATION_AUTHORITY, handler: legacyApplyMutation });
+updateMutationController.register('apply-full', { name: LEGACY_MUTATION_AUTHORITY, handler: legacyApplyFullMutation });
+updateMutationController.register('rollback', { name: LEGACY_MUTATION_AUTHORITY, handler: legacyRollbackMutation });
+const UPDATE_MUTATION_KINDS = new Map([
+    ['/check', 'check'],
+    ['/apply', 'apply'],
+    ['/apply-full', 'apply-full'],
+    ['/rollback', 'rollback'],
+]);
+export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
+    const kind = UPDATE_MUTATION_KINDS.get(subPath);
+    if (kind === undefined) {
+        sendNotFound(res, `Update route not found: ${subPath}`);
         return;
     }
-    sendNotFound(res, `Update route not found: ${subPath}`);
+    await updateMutationController.dispatch(req, res, { workspaceDir }, kind);
 }

package/console/dist/server/update/mutation-controller.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Mutation Controller — PRI-659 migration boundary.
+ *
+ * Governed by:
+ * - ADR-0023 (PD Installation Architecture Decisions) — runtime is written
+ *   only by sanctioned authorities.
+ * - ADR-0024 (PD Runtime Mutation Governance, D-1) — the Console Web updater
+ *   must converge into a trigger/presentation layer over ReleaseManager; it
+ *   must not remain an independent mutation authority long-term.
+ *
+ * Role:
+ *   The controller is the SINGLE routing point between the HTTP surface
+ *   (`/api/update/*`) and whichever authority actually performs the mutation.
+ *   It owns:
+ *     - the mutation-kind registry (check / apply / apply-full / rollback),
+ *     - authority resolution with an explicit preferred authority
+ *       (`release-manager`, ADR-0024 D-1) and a safe fallback
+ *       (`legacy-console-updater`) until ReleaseManager leaves shadow mode,
+ *     - observability: every dispatched response carries the
+ *       `X-PD-Mutation-Authority` header so operators can see which
+ *       authority served a mutation.
+ *
+ * Non-goals (deliberate):
+ *   - The controller performs NO file mutation itself. It only routes. It is
+ *     therefore not a new mutation authority (asserted by migration tests).
+ *   - It does not wrap, copy, or replace the legacy updater implementation.
+ *     The legacy implementation stays in `routes/update.ts` and registers
+ *     itself here. When ReleaseManager matures, it registers under
+ *     `RELEASE_MANAGER_AUTHORITY` for the same kinds and the route layer
+ *     needs no further change.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Authority that exists today: the inline console updater (routes/update.ts). */
+export declare const LEGACY_MUTATION_AUTHORITY: 'legacy-console-updater';
+/** Authority designated by ADR-0024 D-1 as the long-term mutation authority. */
+export declare const RELEASE_MANAGER_AUTHORITY: 'release-manager';
+/**
+ * Preferred authority for every mutation kind. Until ReleaseManager exits
+ * shadow mode (its apply()/rollback() still refuse with
+ * `shadow_mode_read_only`) nothing registers under this name and resolution
+ * falls back to the legacy authority — preserving current capability
+ * (replace-then-delete, not delete-then-rebuild).
+ */
+export declare const PREFERRED_MUTATION_AUTHORITY: "release-manager";
+export type MutationKind = 'check' | 'apply' | 'apply-full' | 'rollback';
+export declare const MUTATION_KINDS: readonly MutationKind[];
+export interface MutationContext {
+    readonly workspaceDir: string;
+}
+export type MutationHandler = (req: IncomingMessage, res: ServerResponse, ctx: MutationContext) => Promise<void>;
+export interface MutationAuthority {
+    readonly name: string;
+    readonly handler: MutationHandler;
+}
+export interface MutationGovernanceInfo {
+    readonly active: string;
+    readonly preferred: string;
+    readonly fallback: boolean;
+    readonly available: readonly string[];
+}
+export interface ResolvedAuthority {
+    readonly authority: MutationAuthority;
+    readonly fallback: boolean;
+}
+export declare class MutationController {
+    private readonly authorities;
+    register(kind: MutationKind, authority: MutationAuthority): void;
+    unregister(kind: MutationKind, name: string): boolean;
+    hasAuthority(kind: MutationKind, name: string): boolean;
+    /**
+     * Resolve which authority serves `kind`: the preferred authority when
+     * registered, otherwise the legacy authority as an explicit fallback.
+     * Throws when nothing is registered — an unregistered kind must fail loud,
+     * not silently mutate.
+     */
+    resolveAuthority(kind: MutationKind): ResolvedAuthority;
+    /**
+     * Route one mutation request. Response body contract is owned by the
+     * authority handler; the controller only annotates the response with the
+     * resolved authority so governance state is observable per request.
+     */
+    dispatch(req: IncomingMessage, res: ServerResponse, ctx: MutationContext, kind: MutationKind): Promise<void>;
+    /** Governance snapshot for observability and migration tests. */
+    describeGovernance(): Record<MutationKind, MutationGovernanceInfo>;
+}
+/**
+ * Process-wide controller for the `/api/update/*` surface. The legacy
+ * updater registers its handlers at module load of `routes/update.ts`.
+ */
+export declare const updateMutationController: MutationController;

package/console/dist/server/update/mutation-controller.js

@@ -0,0 +1,89 @@
+/** Authority that exists today: the inline console updater (routes/update.ts). */
+export const LEGACY_MUTATION_AUTHORITY = 'legacy-console-updater';
+/** Authority designated by ADR-0024 D-1 as the long-term mutation authority. */
+export const RELEASE_MANAGER_AUTHORITY = 'release-manager';
+/**
+ * Preferred authority for every mutation kind. Until ReleaseManager exits
+ * shadow mode (its apply()/rollback() still refuse with
+ * `shadow_mode_read_only`) nothing registers under this name and resolution
+ * falls back to the legacy authority — preserving current capability
+ * (replace-then-delete, not delete-then-rebuild).
+ */
+export const PREFERRED_MUTATION_AUTHORITY = RELEASE_MANAGER_AUTHORITY;
+export const MUTATION_KINDS = ['check', 'apply', 'apply-full', 'rollback'];
+export class MutationController {
+    authorities = new Map();
+    register(kind, authority) {
+        let table = this.authorities.get(kind);
+        if (table === undefined) {
+            table = new Map();
+            this.authorities.set(kind, table);
+        }
+        table.set(authority.name, authority);
+    }
+    unregister(kind, name) {
+        return this.authorities.get(kind)?.delete(name) ?? false;
+    }
+    hasAuthority(kind, name) {
+        return this.authorities.get(kind)?.has(name) ?? false;
+    }
+    /**
+     * Resolve which authority serves `kind`: the preferred authority when
+     * registered, otherwise the legacy authority as an explicit fallback.
+     * Throws when nothing is registered — an unregistered kind must fail loud,
+     * not silently mutate.
+     */
+    resolveAuthority(kind) {
+        const table = this.authorities.get(kind);
+        if (table === undefined || table.size === 0) {
+            throw new Error(`No mutation authority registered for kind: ${kind}`);
+        }
+        const preferred = table.get(PREFERRED_MUTATION_AUTHORITY);
+        if (preferred !== undefined) {
+            return { authority: preferred, fallback: false };
+        }
+        const legacy = table.get(LEGACY_MUTATION_AUTHORITY);
+        if (legacy !== undefined) {
+            return { authority: legacy, fallback: true };
+        }
+        // Multiple non-preferred, non-legacy authorities: refuse to guess.
+        throw new Error(`No preferred (${PREFERRED_MUTATION_AUTHORITY}) or legacy (${LEGACY_MUTATION_AUTHORITY}) authority registered for kind: ${kind}`);
+    }
+    /**
+     * Route one mutation request. Response body contract is owned by the
+     * authority handler; the controller only annotates the response with the
+     * resolved authority so governance state is observable per request.
+     */
+    // eslint-disable-next-line @typescript-eslint/max-params -- (req, res) mirrors the Node handler shape used across this server
+    async dispatch(req, res, ctx, kind) {
+        const { authority, fallback } = this.resolveAuthority(kind);
+        const headerValue = fallback
+            ? `${authority.name} (preferred: ${PREFERRED_MUTATION_AUTHORITY} not yet available)`
+            : authority.name;
+        res.setHeader('X-PD-Mutation-Authority', headerValue);
+        await authority.handler(req, res, ctx);
+    }
+    /** Governance snapshot for observability and migration tests. */
+    describeGovernance() {
+        const snapshot = {};
+        for (const kind of MUTATION_KINDS) {
+            const table = this.authorities.get(kind);
+            const available = table !== undefined ? [...table.keys()] : [];
+            let info;
+            if (table === undefined || table.size === 0) {
+                info = { active: 'none', preferred: PREFERRED_MUTATION_AUTHORITY, fallback: false, available };
+            }
+            else {
+                const { authority, fallback } = this.resolveAuthority(kind);
+                info = { active: authority.name, preferred: PREFERRED_MUTATION_AUTHORITY, fallback, available };
+            }
+            snapshot[kind] = info;
+        }
+        return snapshot;
+    }
+}
+/**
+ * Process-wide controller for the `/api/update/*` surface. The legacy
+ * updater registers its handlers at module load of `routes/update.ts`.
+ */
+export const updateMutationController = new MutationController();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-principles-disciple",
-  "version": "1.130.3",
+  "version": "1.131.1",
   "description": "Interactive CLI installer for Principles Disciple OpenClaw plugin",
   "type": "module",
   "bin": {