@deepseek-ai/dsh-experimental-webworker-packer 0.1.6-alpha.1

package/lib/types/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/lib/types/bin.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Pack a Preview deployment from this repository: compose and lower the base
+ * image, then write each named fixture overlay and their manifest.
+ *
+ * Usage: dsh-pack-vfs-image --out <file> [--profile web] [--root /dsh]
+ *        node --import tsx/esm src/bin.ts --out ../../apps/web/dist/preview/vfs-image.tar.gz
+ * @module @deepseek-ai/dsh-experimental-webworker-packer/src/bin
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PREVIEW_FIXTURE_MANIFEST_FILE, PREVIEW_FIXTURE_MANIFEST_VERSION, } from '@deepseek-ai/dsh-experimental-webworker-runtime';
+import { packVfsImage, packVfsOverlay } from "./pack.js";
+import { composeProfile, configTrees, describePack, indexWorkspacePackages, previewFixtures, } from "./repository.js";
+/**
+ * Read one `--flag value` pair.
+ * @param name - Flag name without dashes.
+ * @param fallback - Value when the flag is absent.
+ * @returns The value.
+ * @throws When the flag is present with no value, because silently packing the
+ * default profile is worse than stopping.
+ */
+function flag(name, fallback) {
+    const index = process.argv.indexOf(`--${name}`);
+    if (index === -1) {
+        if (fallback !== undefined)
+            return fallback;
+        throw new Error(`dsh-pack-vfs-image: --${name} is required`);
+    }
+    const value = process.argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+        throw new Error(`dsh-pack-vfs-image: --${name} needs a value`);
+    }
+    return value;
+}
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+const profile = flag('profile', 'web');
+const out = flag('out');
+const outputFile = isAbsolute(out) ? out : resolve(process.cwd(), out);
+const result = packVfsImage({
+    config: composeProfile(repoRoot, profile),
+    profile,
+    root: flag('root', '/dsh'),
+    workspaces: indexWorkspacePackages(repoRoot),
+    resolveFrom: repoRoot,
+    configTrees: configTrees(repoRoot),
+});
+if (result.missing.length > 0) {
+    throw new Error(`vfs image: ${String(result.missing.length)} dependencies did not resolve; the image would be incomplete`);
+}
+mkdirSync(dirname(outputFile), { recursive: true });
+writeFileSync(outputFile, result.image);
+const fixtureDefinitions = previewFixtures(repoRoot);
+const fixtureDirectory = join(dirname(outputFile), 'fixtures');
+mkdirSync(fixtureDirectory, { recursive: true });
+const fixtureLines = [];
+const fixtures = fixtureDefinitions.map((fixture) => {
+    const packed = packVfsOverlay(fixture.trees);
+    const file = `fixtures/${fixture.id}.tar.gz`;
+    writeFileSync(join(dirname(outputFile), file), packed.image);
+    fixtureLines.push(`  fixture overlay     ${fixture.id} (${String(packed.image.byteLength)} B compressed)`);
+    return {
+        id: fixture.id,
+        label: fixture.label,
+        description: fixture.description,
+        overlays: [file],
+    };
+});
+const manifest = {
+    version: PREVIEW_FIXTURE_MANIFEST_VERSION,
+    defaultFixture: fixtures[0]?.id ?? null,
+    fixtures,
+};
+writeFileSync(join(dirname(outputFile), PREVIEW_FIXTURE_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+process.stdout.write([...describePack(result, repoRoot, outputFile), ...fixtureLines, ''].join('\n'));
+//# sourceMappingURL=bin.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Build-time packer for the browser runtime's VFS image.
+ * @module @deepseek-ai/dsh-experimental-webworker-packer
+ */
+export { WRAPPER_CONTRACT, type ImageFiles, type TransformOutcome, } from './transform-image.ts';
+export { CONFIG_PATH, DEFAULT_ROOT, MANIFEST_PATH, packVfsImage, packVfsOverlay, type ConfigTree, type ImageTree, type PackOptions, type PackOverlayResult, type PackResult, } from './pack.ts';
+export { composeProfile, configTrees, describePack, indexWorkspacePackages, previewFixtures, type PreviewFixture, } from './repository.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/pack.d.ts

@@ -0,0 +1,105 @@
+import { type ImageFiles, type TransformOutcome } from './transform-image.ts';
+export { DEFAULT_ROOT } from '@deepseek-ai/dsh-experimental-webworker-runtime';
+/** Image path of the manifest; the layout contract's name, re-exported for callers. */
+export declare const MANIFEST_PATH: string;
+/** Image path of the composed profile; the layout contract's name, re-exported for callers. */
+export declare const CONFIG_PATH: string;
+/** One directory tree to copy into the image at a caller-selected mount. */
+export interface ImageTree {
+    /** Image path to mount it at, relative to the virtual root. */
+    readonly mount: string;
+    /** Absolute source directory. */
+    readonly directory: string;
+}
+/** One configuration tree whose plugin rows may extend the package roster. */
+export interface ConfigTree extends ImageTree {
+    /**
+     * Whether plugin names inside its `.yml` files join the materialization closure.
+     * An agent preset mounts plugins the base composition never lists, and creating a
+     * session fails if any of them is missing from the image.
+     */
+    readonly scanRoster?: boolean;
+}
+/** Everything the packer needs that it cannot know by itself. */
+export interface PackOptions {
+    /** Composed profile, `!!js` intact, as the CLI's `--dump-default-config` produced it. */
+    readonly config: string;
+    /** Profile name, recorded in the manifest. */
+    readonly profile: string;
+    /** Virtual root the image mounts under; defaults to {@link DEFAULT_ROOT}. */
+    readonly root?: string;
+    /** Package name to absolute directory, for workspace and vendored packages. */
+    readonly workspaces: ReadonlyMap<string, string>;
+    /** Directory Node-style dependency resolution walks up from for the roster. */
+    readonly resolveFrom: string;
+    /** Config trees to copy in beside the composition. */
+    readonly configTrees?: readonly ConfigTree[];
+    /** Empty directories to create; defaults to `home/`, `workspace/`, `tmp/`. */
+    readonly emptyDirectories?: readonly string[];
+    /**
+     * Extra sweep roots: image specifiers requested by code outside the image.
+     * Defaults to the worker assembly's own entries.
+     */
+    readonly entries?: readonly string[];
+}
+/** What one pack produced, for the caller to report or assert on. */
+export interface PackResult {
+    /** The gzip-compressed tar archive to write; the runtime inflates it at mount. */
+    readonly image: Uint8Array;
+    /** Every entry, before zipping; the manifest is already among them. */
+    readonly files: ImageFiles;
+    /** Package name to how many files it contributed, in materialization order. */
+    readonly packages: ReadonlyMap<string, number>;
+    /** How many of them came from the workspace rather than from `node_modules`. */
+    readonly workspacePackages: number;
+    /** Roster package names the closure started from. */
+    readonly roster: readonly string[];
+    /** Dependencies that did not resolve; a non-empty list means an incomplete image. */
+    readonly missing: readonly string[];
+    /** Executable scripts dropped from the image. */
+    readonly executables: readonly string[];
+    /** Page bundles left out of the transform; like every JavaScript entry they carry the trailing debugger name. */
+    readonly pageBundles: readonly string[];
+    /** JavaScript entries the image carries. */
+    readonly javascriptEntries: number;
+    /** JavaScript candidates no root reaches, dropped from the image. */
+    readonly droppedJavascriptEntries: number;
+    /** Third-party requests that resolve nowhere; loud at require time if hit. */
+    readonly unresolvedExternalRequests: readonly string[];
+    /** What the pack-time transform did. */
+    readonly transform: TransformOutcome;
+    /** Wrapper contract recorded in the manifest; every packed body meets it. */
+    readonly contract: string;
+}
+/** One deterministic data-overlay archive and its uncompressed entries. */
+export interface PackOverlayResult {
+    /** Gzip-compressed ustar bytes consumed by the Worker host. */
+    readonly image: Uint8Array;
+    /** Every path in the overlay before compression. */
+    readonly files: ImageFiles;
+}
+/**
+ * Pack one VFS image.
+ *
+ * The manifest's claim is all-or-nothing: it names the one contract every packed body
+ * was emitted against. A module the transform cannot express therefore fails the pack
+ * rather than downgrading the image, because a mostly-transformed image boots into
+ * errors far from their cause.
+ * @param options - Composition, package index, and paths.
+ * @returns The compressed image plus what went into it.
+ * @throws When a config tree or workspace directory named in the options is missing,
+ * because a silently thinner image fails much later and much less clearly.
+ */
+export declare function packVfsImage(options: PackOptions): PackResult;
+/**
+ * Pack opaque data trees into one ordered VFS overlay.
+ *
+ * Overlay mounts are restricted to the runtime-owned data directories, so an
+ * overlay cannot replace configuration, the lowering manifest, or modules.
+ * Files bypass package excludes and module reachability processing; later
+ * trees replace earlier files at the same path.
+ * @param trees - Absolute source directories and their data-directory mounts.
+ * @returns Deterministic compressed archive plus its uncompressed entries.
+ */
+export declare function packVfsOverlay(trees: readonly ImageTree[]): PackOverlayResult;
+//# sourceMappingURL=pack.d.ts.map

package/lib/types/repository.d.ts

@@ -0,0 +1,61 @@
+import type { ConfigTree, ImageTree, PackResult } from './pack.ts';
+/** One built-in Preview source and the trees packed into its overlay. */
+export interface PreviewFixture {
+    /** URL/query-safe identifier. */
+    readonly id: string;
+    /** User-facing chooser label. */
+    readonly label: string;
+    /** User-facing chooser detail. */
+    readonly description: string;
+    /** Opaque trees packed into this fixture's overlay archive. */
+    readonly trees: readonly ImageTree[];
+}
+/**
+ * Index every workspace and vendored package by name.
+ * @param repoRoot - Absolute repository root.
+ * @returns Package name to absolute directory.
+ */
+export declare function indexWorkspacePackages(repoRoot: string): Map<string, string>;
+/**
+ * Compose one profile through the real CLI dump path, leaving `!!js`
+ * unevaluated. The dump runs against a throwaway Harness home and default
+ * layers only, so the image is the shipped profile: the machine's `$DSH_HOME`
+ * — its profile manifest with locally installed bundles, and its patch files —
+ * would otherwise leak this machine's plugins into the image and break the
+ * same-tree-same-bytes guarantee.
+ * @param repoRoot - Absolute repository root.
+ * @param profile - Profile name to compose.
+ * @returns The composed YAML.
+ */
+export declare function composeProfile(repoRoot: string, profile: string): string;
+/**
+ * Config trees the CLI package declares for deployment images
+ * (`dsh.configTrees` in its package.json): `path` is relative to the CLI
+ * package root, `mount` is the image path, `scanRoster` feeds the tree's yml
+ * plugin rows into the pack roster. The CLI owns its config layout; this
+ * reader follows the declaration instead of naming directories. A malformed
+ * declaration refuses the pack.
+ * @param repoRoot - Absolute repository root.
+ * @returns Trees with absolute source directories.
+ */
+export declare function configTrees(repoRoot: string): ConfigTree[];
+/**
+ * Built-in filesystem fixtures offered by the repository preview.
+ * Session and Workspace semantics remain opaque here; the owning runtime tests
+ * validate those files through their production readers.
+ * @param repoRoot - Absolute repository root.
+ * @returns Named chooser entries and their overlay trees.
+ */
+export declare function previewFixtures(repoRoot: string): PreviewFixture[];
+/**
+ * Render one pack as the lines a build log should carry.
+ *
+ * Refusals and unresolved dependencies are the two states a reader must not miss, so
+ * they are spelled out rather than counted.
+ * @param result - What the pack produced.
+ * @param repoRoot - Absolute repository root, for relative paths.
+ * @param outputFile - Where the image was written.
+ * @returns Lines to print.
+ */
+export declare function describePack(result: PackResult, repoRoot: string, outputFile: string): string[];
+//# sourceMappingURL=repository.d.ts.map

package/lib/types/rules.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pack rule tables: the one place the image's include/exclude decisions live.
+ * Patterns are picomatch globs. Exclude patterns match tree-root-relative
+ * paths (so `src/**` drops only a root-level source tree), page-asset
+ * patterns match image paths. Traversal mechanics — nested `node_modules`
+ * flattening and dot-directory pruning — stay in the collector; these tables
+ * hold the judgement calls.
+ */
+/**
+ * Paths dropped from every collected tree. Test trees, sourcemaps,
+ * declarations, and archives never resolve at runtime while dominating the
+ * byte count. Third-party `src/` directories remain eligible because package
+ * entrypoints may resolve to JavaScript there.
+ */
+export declare const EXCLUDE: readonly string[];
+/**
+ * Additional paths dropped from workspace and vendored packages only. Their
+ * runtime plane is built `lib/`; a workspace `dist/` is a page-asset tree the
+ * static deployment serves itself. External packages may place runtime code
+ * under either directory.
+ */
+export declare const EXCLUDE_WORKSPACE: readonly string[];
+/**
+ * Image paths that belong to the PAGE, not to the worker's loader.
+ *
+ * A package's `lib/client.js` is its browser bundle behind the `./client`
+ * export: the page's own module system evaluates it with its own wrapper,
+ * which has no ambient-store parameter. Transforming those bodies would
+ * inject calls the page cannot resolve, so they ship untransformed — their
+ * only change is the trailing debugger-name line every JavaScript entry
+ * gains — and the manifest's all-or-nothing claim stays true, because the
+ * worker loader never evaluates them (the tunnel serves them as bytes).
+ */
+export declare const PAGE_ASSETS: readonly string[];
+/**
+ * Image specifiers the worker assembly requires directly, beyond the composed
+ * roster: they are requested by worker-bundle code, so no image file
+ * references them and the reachability sweep must seed them as roots. Keep in
+ * step with the literal `require`/`resolve` calls in the runtime's
+ * `worker-host.ts`.
+ */
+export declare const IMAGE_ENTRY_SEEDS: readonly string[];
+//# sourceMappingURL=rules.d.ts.map

package/lib/types/transform-image.d.ts

@@ -0,0 +1,12 @@
+/** Image entries, keyed by their path relative to the virtual root. */
+export type ImageFiles = Record<string, Uint8Array>;
+/** Wrapper contract the packed bodies are emitted against. */
+export declare const WRAPPER_CONTRACT: string;
+/** What one pack-time transform pass did. */
+export interface TransformOutcome {
+    /** JavaScript entries visited. */
+    readonly visited: number;
+    /** How many changed; the rest were already in final form. */
+    readonly rewritten: number;
+}
+//# sourceMappingURL=transform-image.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@deepseek-ai/dsh-experimental-webworker-packer",
+  "description": "Build-time packer for the browser runtime's base VFS image and ordered data-overlay archives",
+  "version": "0.1.6-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/experimental/webworker-packer"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "bin": {
+    "dsh-pack-vfs-image": "./bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/bin.js",
+    "bin.js",
+    "lib/repository-*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "js-yaml": "^4.2.0",
+    "picomatch": "^4.0.4",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/dsh-experimental-webworker-runtime": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-home-paths": "^0.1.6-alpha.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/picomatch": "^3.0.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}