@principles/install-layout 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+export declare const INSTALL_LAYOUT_VERSION: 1;
+export declare const INSTALL_LAYOUT_MODES: readonly ["canonical", "legacy"];
+export type InstallLayoutMode = (typeof INSTALL_LAYOUT_MODES)[number];
+export declare const INSTALL_HOSTS: readonly ["codex", "openclaw"];
+export type InstallHost = (typeof INSTALL_HOSTS)[number];
+export interface InstallManifest {
+    layoutVersion: typeof INSTALL_LAYOUT_VERSION;
+    mode: InstallLayoutMode;
+    hosts: InstallHost[];
+}
+export interface InstallLayoutPaths {
+    homeDir: string;
+    pdDir: string;
+    manifest: string;
+    runtimeDir: string;
+    pluginDir: string;
+    installLayoutDir: string;
+    coreDir: string;
+    hostRuntimeDir: string;
+    pdCliDir: string;
+    consoleDir: string;
+    binDir: string;
+    codexDir: string;
+    openClawDir: string;
+    openClawExtensionDir: string;
+}
+export interface LayoutResolution {
+    mode: InstallLayoutMode | 'missing';
+    paths: InstallLayoutPaths;
+    manifest?: InstallManifest;
+    reason?: string;
+    nextAction?: string;
+}
+export interface ResolveInstallLayoutOptions {
+    homeDir: string;
+    manifest?: unknown;
+    canonicalRuntimeExists: boolean;
+    legacyExtensionExists: boolean;
+}
+export declare function parseInstallManifest(value: unknown): {
+    manifest?: InstallManifest;
+    error?: string;
+};
+export declare function getInstallLayoutPaths(homeDir: string): InstallLayoutPaths;
+export declare function resolveInstallLayout(options: ResolveInstallLayoutOptions): LayoutResolution;
+export declare function getConsoleServerEntry(paths: InstallLayoutPaths, mode: InstallLayoutMode): string;
+export declare function getConsoleWebIndex(paths: InstallLayoutPaths, mode: InstallLayoutMode): string;
+export declare function getPdCliEntry(paths: InstallLayoutPaths, mode: InstallLayoutMode): string;

package/dist/index.js

@@ -0,0 +1,81 @@
+import * as path from 'node:path';
+export const INSTALL_LAYOUT_VERSION = 1;
+export const INSTALL_LAYOUT_MODES = ['canonical', 'legacy'];
+export const INSTALL_HOSTS = ['codex', 'openclaw'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isHost(value) {
+    return typeof value === 'string' && INSTALL_HOSTS.includes(value);
+}
+export function parseInstallManifest(value) {
+    if (!isRecord(value))
+        return { error: 'install_manifest_malformed: expected an object' };
+    if (value.layoutVersion !== INSTALL_LAYOUT_VERSION) {
+        return { error: `install_manifest_unsupported_version: ${String(value.layoutVersion)}` };
+    }
+    if (value.mode !== 'canonical' && value.mode !== 'legacy') {
+        return { error: 'install_manifest_malformed: mode must be canonical or legacy' };
+    }
+    if (!Array.isArray(value.hosts) || value.hosts.length === 0 || !value.hosts.every(isHost)) {
+        return { error: 'install_manifest_malformed: hosts must contain codex and/or openclaw' };
+    }
+    const hosts = [...new Set(value.hosts)];
+    return { manifest: { layoutVersion: INSTALL_LAYOUT_VERSION, mode: value.mode, hosts } };
+}
+export function getInstallLayoutPaths(homeDir) {
+    const home = path.resolve(homeDir);
+    const pdDir = path.join(home, '.pd');
+    const runtimeDir = path.join(pdDir, 'runtime');
+    const openClawDir = path.join(home, '.openclaw');
+    return {
+        homeDir: home,
+        pdDir,
+        manifest: path.join(pdDir, 'install.json'),
+        runtimeDir,
+        pluginDir: path.join(runtimeDir, 'plugin'),
+        installLayoutDir: path.join(runtimeDir, 'install-layout'),
+        coreDir: path.join(runtimeDir, 'core'),
+        hostRuntimeDir: path.join(runtimeDir, 'host-runtime'),
+        pdCliDir: path.join(runtimeDir, 'pd-cli'),
+        consoleDir: path.join(runtimeDir, 'console'),
+        binDir: path.join(runtimeDir, 'bin'),
+        codexDir: path.join(pdDir, 'codex'),
+        openClawDir,
+        openClawExtensionDir: path.join(openClawDir, 'extensions', 'principles-disciple'),
+    };
+}
+export function resolveInstallLayout(options) {
+    const paths = getInstallLayoutPaths(options.homeDir);
+    const parsed = parseInstallManifest(options.manifest);
+    if (parsed.manifest && parsed.manifest.mode === 'canonical' && options.canonicalRuntimeExists) {
+        return { mode: 'canonical', paths, manifest: parsed.manifest };
+    }
+    if (options.legacyExtensionExists) {
+        return {
+            mode: 'legacy',
+            paths,
+            ...(parsed.manifest ? { manifest: parsed.manifest } : {}),
+            reason: parsed.error ?? 'install_layout_legacy_fallback',
+            nextAction: 'Run the installer update to migrate the shared runtime to ~/.pd/runtime.',
+        };
+    }
+    return {
+        mode: 'missing',
+        paths,
+        reason: parsed.error ?? 'install_runtime_missing',
+        nextAction: 'Run npx create-principles-disciple to install or repair PD.',
+    };
+}
+export function getConsoleServerEntry(paths, mode) {
+    const root = mode === 'canonical' ? paths.consoleDir : path.join(paths.openClawExtensionDir, 'console');
+    return path.join(root, 'dist', 'server.js');
+}
+export function getConsoleWebIndex(paths, mode) {
+    const root = mode === 'canonical' ? paths.consoleDir : path.join(paths.openClawExtensionDir, 'console');
+    return path.join(root, 'dist', 'web', 'index.html');
+}
+export function getPdCliEntry(paths, mode) {
+    const root = mode === 'canonical' ? paths.pdCliDir : path.join(paths.openClawExtensionDir, 'pd-cli');
+    return path.join(root, 'dist', 'index.js');
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { getInstallLayoutPaths, getConsoleServerEntry, parseInstallManifest, resolveInstallLayout } from './index.js';
+describe('install layout', () => {
+    it('resolves a canonical Codex-only install without OpenClaw', () => {
+        const paths = getInstallLayoutPaths('C:/Users/alice');
+        const result = resolveInstallLayout({
+            homeDir: 'C:/Users/alice',
+            manifest: { layoutVersion: 1, mode: 'canonical', hosts: ['codex'] },
+            canonicalRuntimeExists: true,
+            legacyExtensionExists: false,
+        });
+        expect(result.mode).toBe('canonical');
+        expect(result.manifest?.hosts).toEqual(['codex']);
+        expect(paths.openClawExtensionDir).toContain('.openclaw');
+        expect(paths.pluginDir).toContain('plugin');
+        expect(paths.installLayoutDir).toContain('install-layout');
+        expect(getConsoleServerEntry(result.paths, 'canonical')).toContain('.pd');
+    });
+    it('falls back to legacy only when the old extension exists', () => {
+        const result = resolveInstallLayout({
+            homeDir: '/home/alice',
+            manifest: undefined,
+            canonicalRuntimeExists: false,
+            legacyExtensionExists: true,
+        });
+        expect(result.mode).toBe('legacy');
+        expect(result.nextAction).toContain('migrate');
+    });
+    it('rejects malformed manifests instead of silently treating them as canonical', () => {
+        expect(parseInstallManifest({ layoutVersion: 1, mode: 'canonical', hosts: ['wat'] })).toEqual({
+            error: 'install_manifest_malformed: hosts must contain codex and/or openclaw',
+        });
+    });
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@principles/install-layout",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}