@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.1

package/lib/plugin-management.d.ts

@@ -0,0 +1,5 @@
+/** `@zhin.js/gateway/plugin-management` — project-level package transactions (install / uninstall / update). */
+export * from './plugin-management/activity.js';
+export * from './plugin-management/config-explanation.js';
+export * from './plugin-management/use-cases.js';
+export * from './plugin-management/workflow.js';

package/lib/plugin-management.js

@@ -0,0 +1,5 @@
+/** `@zhin.js/gateway/plugin-management` — project-level package transactions (install / uninstall / update). */
+export * from './plugin-management/activity.js';
+export * from './plugin-management/config-explanation.js';
+export * from './plugin-management/use-cases.js';
+export * from './plugin-management/workflow.js';

package/lib/project/config-file.d.ts

@@ -0,0 +1,6 @@
+import { type PreparedConfigDocument } from '@zhin.js/plugin-runtime';
+export declare function findConfigFile(cwd: string): string | null;
+export declare function readConfig(filePath: string): Promise<Record<string, unknown>>;
+/** Validates an editable candidate and prepares a write against its original source. */
+export declare function prepareConfigSave(filePath: string, config: Record<string, unknown>, baseConfig?: Record<string, unknown>): Promise<PreparedConfigDocument | undefined>;
+export declare function saveConfig(filePath: string, config: Record<string, unknown>, baseConfig?: Record<string, unknown>): Promise<void>;

package/lib/project/config-file.js

@@ -0,0 +1,58 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { isDeepStrictEqual } from 'node:util';
+import { ConfigDocumentConflictError, createConfigDocument, readApplicationPluginDeclaration } from '@zhin.js/runtime';
+import { ROOT_CONFIG_FILE_NAMES, selectRootConfigFile, } from '@zhin.js/plugin-runtime';
+const loadedConfigSource = Symbol('zhin.cli.loaded-config-source');
+function rememberSource(config, file, snapshot) {
+    Object.defineProperty(config, loadedConfigSource, {
+        value: { file: path.resolve(file), snapshot }, configurable: true, enumerable: false,
+    });
+}
+export function findConfigFile(cwd) {
+    const existing = ROOT_CONFIG_FILE_NAMES
+        .filter((name) => fs.existsSync(path.join(cwd, name)));
+    const selected = selectRootConfigFile(existing);
+    return selected ?? null;
+}
+export async function readConfig(filePath) {
+    const snapshot = await createConfigDocument(filePath).read();
+    readApplicationPluginDeclaration(snapshot.document);
+    const config = structuredClone(snapshot.document);
+    rememberSource(config, filePath, snapshot);
+    return config;
+}
+/** Validates an editable candidate and prepares a write against its original source. */
+export async function prepareConfigSave(filePath, config, baseConfig = config) {
+    readApplicationPluginDeclaration(config);
+    const document = createConfigDocument(filePath);
+    const source = baseConfig[loadedConfigSource];
+    if (source && source.file !== path.resolve(filePath))
+        throw new Error('Loaded configuration belongs to a different file');
+    const current = source?.snapshot ?? await document.read();
+    // Validate even a no-op before a caller writes related dependencies or env.
+    if (source && (await document.read()).revision !== current.revision)
+        throw new ConfigDocumentConflictError(filePath);
+    const patches = [];
+    for (const key of new Set([...Object.keys(current.document), ...Object.keys(config)])) {
+        if (isDeepStrictEqual(current.document[key], config[key]))
+            continue;
+        if (key === 'plugins' && current.document.plugins && config.plugins) {
+            const previous = current.document.plugins;
+            const next = config.plugins;
+            for (const alias of new Set([...Object.keys(previous), ...Object.keys(next)])) {
+                if (isDeepStrictEqual(previous[alias], next[alias]))
+                    continue;
+                patches.push(Object.hasOwn(next, alias) ? { op: 'set', path: ['plugins', alias], value: next[alias] } : { op: 'remove', path: ['plugins', alias] });
+            }
+        }
+        else
+            patches.push(Object.hasOwn(config, key) ? { op: 'set', path: [key], value: config[key] } : { op: 'remove', path: [key] });
+    }
+    return patches.length ? document.prepare(current, patches) : undefined;
+}
+export async function saveConfig(filePath, config, baseConfig = config) {
+    const prepared = await prepareConfigSave(filePath, config, baseConfig);
+    if (prepared)
+        rememberSource(config, filePath, await prepared.commit());
+}

package/lib/project/environment.d.ts

@@ -0,0 +1,13 @@
+import type { EnvironmentLayers, EnvironmentLayersPort } from '@zhin.js/runtime';
+/**
+ * Read project dotenv files into Runtime EnvironmentLayers without changing
+ * the CLI process. `.env.<environment>` deliberately overrides `.env`; the
+ * Runtime applies that overlay after inherited process variables.
+ */
+export declare class ProjectEnvironmentFileSource implements EnvironmentLayersPort {
+    #private;
+    readonly sources: readonly string[];
+    constructor(root: string, environment: string);
+    read(): Promise<Readonly<EnvironmentLayers>>;
+}
+export declare function loadRuntimeEnvironmentLayers(root: string, environment: string): Promise<Readonly<EnvironmentLayers>>;

package/lib/project/environment.js

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parse as parseDotenv } from 'dotenv';
+function processEnvironmentSource() {
+    const result = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key))
+            continue;
+        result[key] = value;
+    }
+    return Object.freeze(result);
+}
+/**
+ * Read project dotenv files into Runtime EnvironmentLayers without changing
+ * the CLI process. `.env.<environment>` deliberately overrides `.env`; the
+ * Runtime applies that overlay after inherited process variables.
+ */
+export class ProjectEnvironmentFileSource {
+    sources;
+    #environment;
+    #base;
+    constructor(root, environment) {
+        this.#environment = environment;
+        this.#base = processEnvironmentSource();
+        this.sources = Object.freeze([
+            resolve(root, '.env'),
+            resolve(root, `.env.${environment}`),
+        ]);
+    }
+    async read() {
+        const overlay = {};
+        for (const file of this.sources) {
+            try {
+                Object.assign(overlay, parseDotenv(await readFile(file, 'utf8')));
+            }
+            catch (error) {
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+        }
+        return Object.freeze({
+            base: this.#base,
+            environments: Object.freeze({
+                [this.#environment]: Object.freeze(overlay),
+            }),
+        });
+    }
+}
+export function loadRuntimeEnvironmentLayers(root, environment) {
+    return new ProjectEnvironmentFileSource(root, environment).read();
+}

package/lib/project/instance-declarations.d.ts

@@ -0,0 +1,55 @@
+type SourceState = Readonly<{
+    exists: boolean;
+    source: string;
+    digest: string;
+    mode: number;
+}>;
+export interface InstanceMigrationFile {
+    readonly path: string;
+    readonly before: SourceState;
+    readonly after: SourceState;
+}
+export interface InstanceDeclarationMigrationPlan {
+    readonly root: string;
+    readonly files: readonly InstanceMigrationFile[];
+    /** Package manifests consulted during static resolution. No plugin entry is imported. */
+    readonly guards: readonly Readonly<{
+        path: string;
+        digest: string;
+    }>[];
+    readonly instances: readonly Readonly<{
+        instanceKey: string;
+        package: string;
+        pluginId: string;
+        enabled: boolean;
+    }>[];
+    readonly pendingChecks: readonly string[];
+}
+export interface InstanceMigrationApplyOptions {
+    /** Fault-injection seam: invoked after each durable file replacement. */
+    readonly afterWrite?: (index: number) => void | Promise<void>;
+    /** Clock seam for the human-readable backup directory name. */
+    readonly now?: () => Date;
+}
+export interface InstanceMigrationApplyResult {
+    /** Timestamped copy of every original file, independent of the recovery journal. */
+    readonly backupDirectory: string;
+}
+/** Static, offline and side-effect-free. Does not load schemas from executable entries. */
+export declare function planInstanceDeclarationMigration(projectRoot: string, options?: {
+    readonly lifecycleFile?: string;
+}): Promise<InstanceDeclarationMigrationPlan>;
+export declare function assertNoPendingInstanceMigration(root: string): Promise<void>;
+export declare function applyInstanceDeclarationMigration(plan: InstanceDeclarationMigrationPlan, options?: InstanceMigrationApplyOptions): Promise<InstanceMigrationApplyResult>;
+/**
+ * Human-readable, value-free preview of a migration plan. Only key names, package
+ * specifiers and instance state are shown; configuration values (including
+ * environment references) never appear, so the output is safe to paste in issues.
+ */
+export declare function formatInstanceMigrationPreview(plan: InstanceDeclarationMigrationPlan, options?: {
+    readonly mode?: 'dry-run' | 'apply';
+}): string;
+export declare function recoverInstanceDeclarationMigration(rootPath: string, action: 'continue' | 'rollback', options?: InstanceMigrationApplyOptions): Promise<void>;
+export declare function assertStopped(root: string): Promise<void>;
+export declare function withProjectLock<T>(root: string, operation: () => Promise<T>, recovery?: boolean): Promise<T>;
+export {};