@gestaltrun/dsh-workspace-bundle 0.0.0-stage → 0.1.0

package/lib/types/journal.js

@@ -0,0 +1,109 @@
+/** Durable upgrade journal: staging → updating → swap → verify → commit, with crash recovery. */
+import { basename, dirname, join } from 'node:path';
+import { bundledDirectory } from "./paths.js";
+import { WorkspaceBundleError } from "./errors.js";
+const IDLE = {
+    phase: 'idle',
+    fromDigest: null,
+    toDigest: null,
+    pluginVersion: null,
+    stagingPath: null,
+    backupPath: null,
+    swapComplete: false,
+};
+/** @returns a journal with no in-flight replacement. */
+export function idleJournal() {
+    return IDLE;
+}
+/**
+ * @param parent - journal root from Spec.
+ * @param identity - bundled Workspace.
+ */
+export function journalPath(parent, identity) {
+    return join(bundledDirectory(parent, identity), 'journal.json');
+}
+/**
+ * @param parent - journal root from Spec.
+ * @param identity - bundled Workspace.
+ */
+export function recordPath(parent, identity) {
+    return join(bundledDirectory(parent, identity), 'record.json');
+}
+async function writeJson(fs, path, value) {
+    const tmp = `${path}.tmp`;
+    await fs.writeFile(tmp, `${JSON.stringify(value)}\n`);
+    await fs.rename(tmp, path);
+}
+/**
+ * Persist the product record.
+ * @param fs - filesystem.
+ * @param path - record.json path.
+ * @param record - value.
+ */
+export async function writeRecord(fs, path, record) {
+    await writeJson(fs, path, record);
+}
+/**
+ * Read a product record when present.
+ * @param fs - filesystem.
+ * @param path - record.json path.
+ */
+export async function readRecord(fs, path) {
+    if (!await fs.exists(path))
+        return undefined;
+    const value = JSON.parse((await fs.readFile(path)).toString('utf8'));
+    if (value.version !== 1)
+        throw new Error(`workspace-bundle: unsupported record version ${String(value.version)}`);
+    return value;
+}
+async function canonicalPath(fs, path) {
+    try {
+        return await fs.realpath(path);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT' || dirname(path) === path)
+            throw error;
+        // A replacement can leave root or staging absent; existing ancestors still resolve directory aliases.
+        return join(await canonicalPath(fs, dirname(path)), basename(path));
+    }
+}
+/**
+ * Reject stored paths whose canonical locations differ from the identity's controlled directories.
+ * @param fs - filesystem used by recovery, including realpath resolution.
+ * @param record - stored product record.
+ * @param root - materialize directory derived from the requested identity and current Spec.
+ * @returns fulfills when every stored path has the same canonical location as its controlled directory.
+ * @throws {WorkspaceBundleError} Before recovery mutates files when a stored path differs.
+ */
+export async function assertRecordPaths(fs, record, root) {
+    for (const [stored, controlled] of [
+        [record.path, root],
+        [record.journal.stagingPath, `${root}.staging`],
+        [record.journal.backupPath, `${root}.backup`],
+    ]) {
+        if (stored !== null && await canonicalPath(fs, stored) !== await canonicalPath(fs, controlled)) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_PATH_TRAVERSAL', `stored Workspace paths must match the canonical controlled directory ${controlled}`);
+        }
+    }
+}
+/**
+ * Persist the journal as part of the product record.
+ * @param fs - filesystem.
+ * @param path - record.json path.
+ * @param record - current record.
+ * @param journal - next journal.
+ */
+export async function writeJournal(fs, path, record, journal) {
+    const next = { ...record, journal };
+    await writeRecord(fs, path, next);
+    return next;
+}
+/**
+ * Mark a replacement as committed: idle journal, new digest and plugin version.
+ * @param record - current record.
+ * @param digest - verified tree digest.
+ * @param pluginVersion - packaged plugin version.
+ */
+export function committedRecord(record, digest, pluginVersion) {
+    return { ...record, pluginVersion, templateDigest: digest, journal: idleJournal(), lastFailure: null };
+}

package/lib/types/paths.d.ts

@@ -0,0 +1,26 @@
+import type { WorkspaceBundleId, WorkspaceBundleKey } from '@deepseek-ai/dsh-workspace/types';
+import type { WorkspaceBundleIdentity } from './types.ts';
+/**
+ * Encode one branded identity as a single path segment.
+ * @param value - bundle id or workspace key.
+ * @param field - diagnostic name.
+ * @returns the same spelling when it is a controlled segment.
+ * @throws {WorkspaceBundleError} When the value could traverse or collide with `.` / `..`.
+ */
+export declare function encodeBundleSegment(value: string, field: 'bundleId' | 'workspaceKey'): string;
+/**
+ * Join a parent with `{bundleId}/{workspaceKey}`.
+ * @param parent - absolute parent already validated by Config.
+ * @param identity - branded pair.
+ * @returns the joined path using the host separator.
+ */
+export declare function bundledDirectory(parent: string, identity: WorkspaceBundleIdentity): string;
+/**
+ * Reject a template-relative path that leaves the root, is absolute, or uses a reserved segment.
+ * @param relativePath - POSIX relative path from the manifest.
+ * @returns the same spelling.
+ * @throws {WorkspaceBundleError} On traversal, absolute paths, empty segments, or backslashes.
+ */
+export declare function assertTemplateRelativePath(relativePath: string): string;
+/** @param bundleId - branded bundle identity. @param workspaceKey - branded workspace key. */
+export declare function identityOf(bundleId: WorkspaceBundleId, workspaceKey: WorkspaceBundleKey): WorkspaceBundleIdentity;

package/lib/types/paths.js

@@ -0,0 +1,48 @@
+/** Controlled encoding of branded Workspace bundle identities into Home path segments. */
+import { join, posix, sep } from 'node:path';
+import { WorkspaceBundleError } from "./errors.js";
+const SEGMENT = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+/**
+ * Encode one branded identity as a single path segment.
+ * @param value - bundle id or workspace key.
+ * @param field - diagnostic name.
+ * @returns the same spelling when it is a controlled segment.
+ * @throws {WorkspaceBundleError} When the value could traverse or collide with `.` / `..`.
+ */
+export function encodeBundleSegment(value, field) {
+    if (!SEGMENT.test(value) || value === '.' || value === '..' || value.includes(sep) || value.includes(posix.sep) || value.includes('\0')) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_IDENTITY_INVALID', `${field} ${JSON.stringify(value)} is not a controlled path segment`);
+    }
+    return value;
+}
+/**
+ * Join a parent with `{bundleId}/{workspaceKey}`.
+ * @param parent - absolute parent already validated by Config.
+ * @param identity - branded pair.
+ * @returns the joined path using the host separator.
+ */
+export function bundledDirectory(parent, identity) {
+    return join(parent, encodeBundleSegment(identity.bundleId, 'bundleId'), encodeBundleSegment(identity.workspaceKey, 'workspaceKey'));
+}
+/**
+ * Reject a template-relative path that leaves the root, is absolute, or uses a reserved segment.
+ * @param relativePath - POSIX relative path from the manifest.
+ * @returns the same spelling.
+ * @throws {WorkspaceBundleError} On traversal, absolute paths, empty segments, or backslashes.
+ */
+export function assertTemplateRelativePath(relativePath) {
+    if (relativePath === '' || relativePath.startsWith('/') || relativePath.includes('\\') || relativePath.includes('\0')) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_PATH_TRAVERSAL', `template path ${JSON.stringify(relativePath)} is not a relative POSIX path`);
+    }
+    const parts = relativePath.split('/');
+    if (parts.some(part => part === '' || part === '.' || part === '..')) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_PATH_TRAVERSAL', `template path ${JSON.stringify(relativePath)} contains a reserved segment`);
+    }
+    return relativePath;
+}
+/** @param bundleId - branded bundle identity. @param workspaceKey - branded workspace key. */
+export function identityOf(bundleId, workspaceKey) {
+    encodeBundleSegment(bundleId, 'bundleId');
+    encodeBundleSegment(workspaceKey, 'workspaceKey');
+    return { bundleId, workspaceKey };
+}

package/lib/types/provider.d.ts

@@ -0,0 +1,77 @@
+import { Context } from '@deepseek-ai/cordis';
+import type { Workspace, WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+import { Config } from './config.ts';
+import { WorkspaceBundles } from './definition.ts';
+import type { WorkspaceAgentConfigSource, WorkspaceAgentConfigState } from './agent-config-types.ts';
+import type { WorkspaceBundleCrashPoint, WorkspaceBundleFs, WorkspaceBundleIdentity, WorkspaceBundleRecord, WorkspaceBundlesSpec, WorkspaceTemplate } from './types.ts';
+/** Provider for packaged Workspace templates. */
+export declare class GestaltWorkspaceBundles extends WorkspaceBundles {
+    static inject: string[];
+    static Config: import("@deepseek-ai/schemastery").default<Config, import("./config.ts").ResolvedConfig>;
+    /** Deployment settings resolved at load. */
+    readonly spec: WorkspaceBundlesSpec;
+    private readonly fs;
+    private readonly templates;
+    private readonly agentConfigSources;
+    private readonly records;
+    private readonly leases;
+    private readonly waiters;
+    private chain;
+    private readonly recycle;
+    private readonly recycleWork;
+    private closed;
+    private readonly download;
+    /**
+     * @param ctx - Host context with the Workspace registry.
+     * @param config - raw row settings.
+     * @param options.fs - filesystem; tests inject crashes through `crashAt`.
+     * @param options.crashAt - single crash point; production omits it.
+     * @param options.fetch - 文件 HTTP 传输；默认使用 Host fetch。
+     */
+    constructor(ctx: Context, config?: Config, options?: {
+        fs?: WorkspaceBundleFs;
+        crashAt?: WorkspaceBundleCrashPoint;
+        fetch?: typeof fetch;
+    });
+    /** @inheritdoc */
+    register(template: WorkspaceTemplate): () => void;
+    /** @inheritdoc */
+    ensure(identity: WorkspaceBundleIdentity): Promise<Workspace>;
+    /** @inheritdoc */
+    registerAgentConfigSource(source: WorkspaceAgentConfigSource): () => Promise<void>;
+    /** @inheritdoc */
+    agentConfig(identity: WorkspaceBundleIdentity): WorkspaceAgentConfigState | undefined;
+    /** @inheritdoc */
+    refreshAgentConfig(identity: WorkspaceBundleIdentity): Promise<void>;
+    /** @inheritdoc */
+    acquire(workspaceId: WorkspaceId): Promise<() => void>;
+    private acquireOne;
+    /** @inheritdoc */
+    record(identity: WorkspaceBundleIdentity): WorkspaceBundleRecord | undefined;
+    /** @inheritdoc */
+    pathOf(identity: WorkspaceBundleIdentity): string;
+    /**
+     * Replay an interrupted journal before serving the Workspace.
+     * @param identity - branded pair.
+     * @throws {WorkspaceBundleError} Before any rename or deletion if stored paths differ from this identity's controlled paths.
+     */
+    recover(identity: WorkspaceBundleIdentity): Promise<Workspace | undefined>;
+    private enqueue;
+    private ensureOne;
+    private rollbackAgentConfig;
+    private requireTemplate;
+    private stagingOf;
+    private backupOf;
+    private recordFile;
+    private loadStored;
+    private recoverOne;
+    private workspaceOf;
+    private restoreOld;
+    private finishNew;
+    private replace;
+    private commit;
+    private quiesce;
+    private scheduleRecycle;
+    private prepareBackup;
+}
+export default GestaltWorkspaceBundles;