create-principles-disciple 1.147.3 → 1.147.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-principles-disciple",
-  "version": "1.147.3",
+  "version": "1.147.5",
   "description": "Interactive CLI installer for Principles Disciple OpenClaw plugin",
   "type": "module",
   "bin": {
@@ -101,5 +101,5 @@
   "pd": {
     "bundledPluginVersion": "2.5.0"
   },
-  "gitHead": "5c3371c3935192081585d741f50a899bc4445b0e"
+  "gitHead": "29d6fbfd56adcc2d71280438b0bcaf8ee8ef3bd8"
 }

package/release-manager/dist/i18n.js

@@ -105,10 +105,14 @@ const translations = {
         // Install failure / rollback result strings (catch block). EP-11.
         rollback_no_changes: 'No changes were made — the existing install was not modified (no backup was created).',
         rollback_restored: 'Previous install has been restored.',
+        // PRI-1102: the rollback target itself can be incomplete — say so instead
+        // of reporting a restore that leaves the operator with a broken install.
+        rollback_restored_incomplete: 'Rolled back to the state that existed before this run, but that state is NOT usable — incomplete: {paths}.',
         rollback_failed: 'CRITICAL: Rollback also failed — installation state is uncertain. {restoreError} Resolve manually: check {extDir} and {backupDir}',
         next_no_changes_lock: 'A file lock blocked the backup (EPERM). Stop the OpenClaw gateway (openclaw gateway stop, or re-run with --stop-gateway) and retry.',
         next_no_changes_other: 'Fix the error above and re-run the installer. The existing install was not modified.',
         next_restored: 'Check the error above. Previous install has been restored. Fix the issue and re-run the installer.',
+        next_restored_incomplete: 'Check the error above. Rollback returned the pre-run state, but it is incomplete: {paths}. Re-run the installer so the missing components are rebuilt.',
         next_restore_failed: 'Installation and rollback both failed. Check {extDir} and {backupDir} manually. Error: {errorMsg}',
         // CP-6: fresh-install failure mid-deployment (no pre-existing install → no backup).
         rollback_fresh_cleaned: 'The install failed before activation — the partially deployed runtime files were removed. Nothing else was modified.',
@@ -225,10 +229,12 @@ const translations = {
         // 安装失败 / 回滚结果字符串（catch 块）。EP-11。
         rollback_no_changes: '未做任何改动 —— 现有安装未被修改（未创建备份）。',
         rollback_restored: '已恢复到之前的安装。',
+        rollback_restored_incomplete: '已回滚到本次运行之前的状态，但该状态本身不可用 —— 不完整：{paths}。',
         rollback_failed: '严重：回滚也失败了 —— 安装状态不确定。{restoreError} 请手动处理：检查 {extDir} 和 {backupDir}',
         next_no_changes_lock: '文件锁阻塞了备份 (EPERM)。请停止 OpenClaw gateway（openclaw gateway stop，或用 --stop-gateway 重新运行）后重试。',
         next_no_changes_other: '请修复上方错误后重新运行安装器。现有安装未被修改。',
         next_restored: '请检查上方错误。已恢复到之前的安装。修复问题后重新运行安装器。',
+        next_restored_incomplete: '请检查上方错误。回滚返回的是本次运行之前的状态，但该状态不完整：{paths}。请重新运行安装器，让它重建缺失的组件。',
         next_restore_failed: '安装与回滚均失败。请手动检查 {extDir} 和 {backupDir}。错误：{errorMsg}',
         // CP-6：全新安装部署中途失败（无既有安装 → 无备份）。
         rollback_fresh_cleaned: '安装未激活即失败 —— 已移除本次部署的部分运行时文件。其余内容未被修改。',

package/release-manager/dist/installer.js

@@ -1553,10 +1553,79 @@ export async function checkBuiltPlugin(pluginDir) {
         }
     }
 }
+/**
+ * PRI-1102: a target that exists as a DANGLING link (an interrupted install
+ * left a reparse point whose target is gone) is not a directory the installer
+ * can copy into. `existsSync` follows the link and reports "missing", so the
+ * backup step never moves it, and `ensureDir` then treats it as present —
+ * the follow-up mkdir fails with ENOENT and aborts the whole install.
+ *
+ * Absent targets are created. A dangling link is removed (the link itself only,
+ * never a target), and the caller recreates the real directory. Everything
+ * else — a real directory, or a link that still resolves — is left untouched,
+ * so an existing install is never destroyed by this step.
+ */
+export async function preparePluginInstallTarget(targetDir) {
+    let stats;
+    try {
+        stats = lstatSync(targetDir, { throwIfNoEntry: false });
+    }
+    catch (error) {
+        throw new Error(`Cannot inspect plugin install target ${targetDir}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (stats !== undefined && stats.isSymbolicLink()) {
+        let resolves = true;
+        try {
+            realpathSync(targetDir);
+        }
+        catch {
+            resolves = false;
+        }
+        if (!resolves) {
+            // fs-extra's remove unlinks the reparse point instead of traversing it.
+            await fse.remove(targetDir);
+            logger.warn(`Removed dangling link at ${targetDir} (target missing) — rebuilding the plugin install directory.`);
+        }
+    }
+    await fse.ensureDir(targetDir);
+}
+/**
+ * PRI-1102: a rollback is only as good as the state it returns to. The
+ * pre-run state can itself be incomplete (a component directory the previous
+ * run never finished, a link whose target is gone), so "restored" must not be
+ * reported as a healthy install without checking what the restored paths
+ * actually resolve to.
+ */
+export function describeRestoredStateGaps() {
+    const gaps = [];
+    for (const dir of [getPluginExtDir(), getPdRuntimeDir()]) {
+        let stats;
+        try {
+            stats = lstatSync(dir, { throwIfNoEntry: false });
+        }
+        catch (error) {
+            gaps.push(`${dir} (unreadable: ${error instanceof Error ? error.message : String(error)})`);
+            continue;
+        }
+        if (stats === undefined) {
+            gaps.push(`${dir} (missing)`);
+            continue;
+        }
+        if (stats.isSymbolicLink()) {
+            try {
+                realpathSync(dir);
+            }
+            catch {
+                gaps.push(`${dir} (dangling link)`);
+            }
+        }
+    }
+    return gaps;
+}
 export async function installPluginToStaging(pluginDir, language) {
     const builtPluginDir = path.join(pluginDir, 'plugin');
     for (const targetDir of pluginInstallDirs()) {
-        await fse.ensureDir(targetDir);
+        await preparePluginInstallTarget(targetDir);
         // PRI-1037 payload fix: npm-era payloads carried a ~16k-file node_modules
         // (the whole pi-ai/openai/anthropic tree, dragged in through the plugin's
         // historical file:./core dependency) plus a `core` junction, in BOTH plugin
@@ -2187,6 +2256,101 @@ function installBundledCodexAdapter(pluginDir) {
     rmSync(codexAdapterDest, { recursive: true, force: true });
     cpSync(codexAdapterSrc, codexAdapterDest, { recursive: true });
 }
+/**
+ * P1: structural package-name validation. Unscoped names have exactly one
+ * segment; scoped names exactly `@scope/pkg`. This is deliberately NOT one
+ * regex: "." / ".." pass a character-class test, yet path.join() normalizes
+ * them onto node_modules / the scope parent / the component root.
+ */
+function isSafeNameSegment(segment) {
+    return segment.length > 0 && segment !== '.' && segment !== '..' && /^[A-Za-z0-9._-]+$/.test(segment);
+}
+function parseDependencyName(name) {
+    const scoped = name.startsWith('@');
+    const raw = (scoped ? name.slice(1) : name).split('/');
+    if (scoped ? raw.length !== 2 : raw.length !== 1)
+        return undefined;
+    if (!raw.every(isSafeNameSegment))
+        return undefined;
+    if (!scoped)
+        return raw;
+    const [scope, packageName] = raw;
+    return scope !== undefined && packageName !== undefined ? [`@${scope}`, packageName] : undefined;
+}
+/**
+ * P1: `target` must be a STRICT descendant of `root` (never root itself, never
+ * `..`, never an absolute escape). Applied to the lexical link path, the real
+ * node_modules directory (which must stay inside the component) and any
+ * symlinked ancestor we are about to create or delete through.
+ */
+function assertStrictlyInside(root, target, componentLabel) {
+    const relative = path.relative(root, target);
+    if (relative === '' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`Installed ${componentLabel} dependency link path escapes the install tree (${target} is not strictly inside ${root}).`);
+    }
+}
+/** P1: an existing path used as a link parent must be a real directory, not a symlink. */
+function assertRealParentDirectory(dir, componentLabel) {
+    let stat;
+    try {
+        stat = lstatSync(dir);
+    }
+    catch (error) {
+        throw new Error(`Installed ${componentLabel} dependency link parent is missing (${dir}): ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Installed ${componentLabel} dependency link parent must not be a symbolic link (${dir}).`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`Installed ${componentLabel} dependency link parent must be a directory (${dir}).`);
+    }
+}
+/**
+ * P1 two-phase planning: resolve + validate every `file:../` dependency and
+ * its final link path without mutating anything. Only a fully valid plan is
+ * returned, so an invalid later entry cannot leave earlier links half-applied.
+ */
+function planComponentFileDependencyLinks(componentDir, componentLabel, dependencies) {
+    const runtimeDir = getPdRuntimeDir();
+    const runtimeDirReal = realpathSync(runtimeDir);
+    const nodeModulesDir = path.join(componentDir, 'node_modules');
+    const operations = [];
+    for (const [name, ref] of Object.entries(dependencies)) {
+        if (typeof ref !== 'string' || !ref.startsWith('file:../'))
+            continue;
+        const siblingName = ref.slice('file:../'.length);
+        // rc-1: only a single ordinary sibling segment; "." / ".." and separators
+        // must not resolve the ref outside the runtime dir.
+        if (!isSafeNameSegment(siblingName)) {
+            throw new Error(`Installed ${componentLabel} declares an unsupported file dependency ref "${ref}" for ${name}.`);
+        }
+        const segments = parseDependencyName(name);
+        if (segments === undefined) {
+            throw new Error(`Installed ${componentLabel} declares an unsupported dependency name "${name}".`);
+        }
+        const siblingDir = path.join(runtimeDir, siblingName);
+        if (!existsSync(siblingDir)) {
+            throw new Error(`${componentLabel} depends on ${ref} but the sibling runtime component is missing: ${siblingDir}`);
+        }
+        const siblingReal = realpathSync(siblingDir);
+        // The sibling must resolve to exactly <runtime>/<siblingName>: a symlink
+        // that redirects the link target outside the runtime is not a sibling.
+        if (path.relative(runtimeDirReal, siblingReal) !== siblingName) {
+            throw new Error(`Installed ${componentLabel} declares a file dependency ref that resolves outside the runtime dir: "${ref}".`);
+        }
+        const linkPath = path.join(nodeModulesDir, ...segments);
+        // Lexical boundary + segment-count: path.join() collapses "." / ".." and
+        // repeated separators, so the normalized path must still have exactly the
+        // declared number of segments and be a strict descendant of node_modules.
+        const relative = path.relative(nodeModulesDir, linkPath);
+        if (relative.split(path.sep).length !== segments.length) {
+            throw new Error(`Installed ${componentLabel} declares an unsupported dependency name "${name}".`);
+        }
+        assertStrictlyInside(nodeModulesDir, linkPath, componentLabel);
+        operations.push({ segments, siblingReal, linkPath });
+    }
+    return operations;
+}
 /**
  * PRI-711 (generalized for ADR-0020 host adapters): materialize node_modules
  * links for an INSTALLED runtime component so its declared `file:../<component>`
@@ -2213,26 +2377,40 @@ function ensureComponentFileDependencyLinks(componentDir, componentLabel) {
     if (manifest.dependencies !== undefined && !isRecord(manifest.dependencies)) {
         throw new Error(`Installed ${componentLabel} package.json dependencies must be an object (${manifestPath}).`);
     }
-    const runtimeDir = getPdRuntimeDir();
-    for (const [name, ref] of Object.entries(manifest.dependencies ?? {})) {
-        if (typeof ref !== 'string' || !ref.startsWith('file:../'))
-            continue;
-        const siblingName = ref.slice('file:../'.length);
-        // rc-1: the manifest is untrusted input — only accept single-path segment
-        // siblings so a crafted ref cannot escape the runtime dir.
-        if (!/^[A-Za-z0-9._-]+$/.test(siblingName) || siblingName === '.' || siblingName === '..') {
-            throw new Error(`Installed ${componentLabel} declares an unsupported file dependency ref "${ref}" for ${name}.`);
-        }
-        const siblingDir = path.join(runtimeDir, siblingName);
-        if (!existsSync(siblingDir)) {
-            throw new Error(`${componentLabel} depends on ${ref} but the sibling runtime component is missing: ${siblingDir}`);
-        }
-        // rc-1: the dependency NAME is manifest input too — it becomes a path
-        // segment under node_modules, so a crafted name must not escape it.
-        if (!/^(@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+$/.test(name)) {
-            throw new Error(`Installed ${componentLabel} declares an unsupported dependency name "${name}".`);
+    // P1: validate EVERYTHING before touching the filesystem. A manifest is
+    // untrusted input, and a name that normalizes to node_modules / the scope
+    // parent / the component root must never reach a recursive delete.
+    const operations = planComponentFileDependencyLinks(componentDir, componentLabel, manifest.dependencies ?? {});
+    if (operations.length === 0)
+        return;
+    const componentDirReal = realpathSync(componentDir);
+    const nodeModulesDir = path.join(componentDir, 'node_modules');
+    // P1: node_modules itself must be a real directory inside the component —
+    // a symlinked parent would redirect every link/delete outside the install.
+    mkdirSync(nodeModulesDir, { recursive: true });
+    assertRealParentDirectory(nodeModulesDir, componentLabel);
+    const nodeModulesReal = realpathSync(nodeModulesDir);
+    assertStrictlyInside(componentDirReal, nodeModulesReal, componentLabel);
+    for (const operation of operations) {
+        const { segments, siblingReal, linkPath } = operation;
+        if (segments.length === 2) {
+            // scoped parent: create only when absent; never replace an existing
+            // real directory (npm may legitimately share it) and never follow a
+            // symlinked parent.
+            const scopeSegment = segments[0];
+            const scopeDir = path.join(nodeModulesDir, scopeSegment);
+            let scopeStat;
+            try {
+                scopeStat = lstatSync(scopeDir);
+            }
+            catch {
+                scopeStat = undefined;
+            }
+            if (scopeStat === undefined)
+                mkdirSync(scopeDir);
+            assertRealParentDirectory(scopeDir, componentLabel);
+            assertStrictlyInside(nodeModulesReal, realpathSync(scopeDir), componentLabel);
         }
-        const linkPath = path.join(componentDir, 'node_modules', name);
         let stat;
         try {
             stat = lstatSync(linkPath);
@@ -2243,21 +2421,23 @@ function ensureComponentFileDependencyLinks(componentDir, componentLabel) {
         if (stat !== undefined) {
             if (stat.isSymbolicLink()) {
                 try {
-                    if (realpathSync(linkPath) === realpathSync(siblingDir))
+                    if (realpathSync(linkPath) === siblingReal)
                         continue;
                 }
                 catch {
                     // Unreadable link target — fall through to replace.
                 }
             }
+            // linkPath was proven to be a strict descendant of node_modules during
+            // planning, and both parent levels were re-verified as real directories
+            // above, so the only recursive delete stays inside the component tree.
             rmSync(linkPath, { recursive: stat.isDirectory() && !stat.isSymbolicLink(), force: true });
         }
-        mkdirSync(path.dirname(linkPath), { recursive: true });
         if (isWindows()) {
-            symlinkSync(siblingDir, linkPath, 'junction');
+            symlinkSync(siblingReal, linkPath, 'junction');
         }
         else {
-            symlinkSync(path.relative(path.dirname(linkPath), siblingDir), linkPath, 'dir');
+            symlinkSync(path.relative(path.dirname(linkPath), siblingReal), linkPath, 'dir');
         }
     }
 }
@@ -4244,6 +4424,10 @@ transaction) {
         // pre-date this run, so it is NOT wholesale-removed. Report its retention
         // honestly instead of claiming "nothing else was modified".
         const workspaceTouched = !hasBackup && mutationStarted && journal?.lastState !== 'planned';
+        // PRI-1102: `restored` describes the rollback operation, not the health of
+        // the state it returned to. Name the gaps so "restored" is never read as
+        // "usable install".
+        const restoredGaps = hasBackup && restoreResult.restored ? describeRestoredStateGaps() : [];
         const rollbackSuffix = !hasBackup
             ? freshCleanup
                 ? freshCleanup.failed.length === 0
@@ -4251,7 +4435,9 @@ transaction) {
                     : t('rollback_fresh_clean_failed').replace('{dirs}', freshCleanup.failed.map((f) => f.dir).join(', '))
                 : t('rollback_no_changes')
             : restoreResult.restored
-                ? t('rollback_restored')
+                ? restoredGaps.length === 0
+                    ? t('rollback_restored')
+                    : t('rollback_restored_incomplete').replace('{paths}', restoredGaps.join(', '))
                 : t('rollback_failed')
                     .replace('{restoreError}', restoreResult.error ?? '')
                     .replace('{extDir}', extDir)
@@ -4268,7 +4454,9 @@ transaction) {
                     ? t('next_no_changes_lock')
                     : t('next_no_changes_other'))
             : restoreResult.restored
-                ? t('next_restored')
+                ? restoredGaps.length === 0
+                    ? t('next_restored')
+                    : t('next_restored_incomplete').replace('{paths}', restoredGaps.join(', '))
                 : t('next_restore_failed')
                     .replace('{extDir}', extDir)
                     .replace('{backupDir}', backupDir ?? runtimeBackupDir ?? '')

package/release-manager/package.json

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