castle-web-cli 0.4.37 → 0.4.38

package/dist/buildArchive.d.ts

@@ -0,0 +1 @@
+export declare function buildKitArchives(kits?: string[]): void;

package/dist/buildArchive.js

@@ -0,0 +1,108 @@
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ARCHIVE_NAME, PUBLISHED_SDK_VERSION, copyKitSource, getKitArchivePath, rewriteKitPackageJson, } from './init.js';
+import { getKitsDir, getSdkPackagePath, toPosixPath } from './localPaths.js';
+// Refs forced to "published" so the archived deck looks like one scaffolded
+// from a globally-installed castle-web (registry sdk + `castle-web` binary),
+// regardless of the workspace checkout we generate it from.
+const PUBLISHED_REFS = {
+    workspaceMode: false,
+    sdkRef: `^${PUBLISHED_SDK_VERSION}`,
+    cliCommand: 'castle-web',
+    cliDistAbs: null,
+    sdkPathPosix: null,
+};
+// Build the local sdk and `npm pack` it into a temp dir, returning the tarball
+// path. Installing a tarball (not a `file:` dir) gives the archive a real copy
+// of the sdk in node_modules instead of a symlink to the local checkout.
+function packSdk() {
+    const sdkDir = getSdkPackagePath();
+    if (!fs.existsSync(sdkDir)) {
+        throw new Error(`sdk/ not found at ${sdkDir}; build-archives must run from a workspace checkout.`);
+    }
+    console.log('Building sdk...');
+    execFileSync('npm', ['run', 'build'], { cwd: sdkDir, stdio: 'inherit' });
+    const dest = fs.mkdtempSync(path.join(os.tmpdir(), 'castle-sdk-pack-'));
+    console.log('Packing sdk...');
+    const out = execFileSync('npm', ['pack', '--pack-destination', dest], {
+        cwd: sdkDir,
+        encoding: 'utf8',
+    }).trim();
+    // npm pack prints the created tarball filename on its last line.
+    const file = out.split('\n').pop().trim();
+    return path.join(dest, file);
+}
+// Find every real kit under kits/ (a subdir with a package.json).
+function discoverKits(kitsDir) {
+    return fs.readdirSync(kitsDir).filter((name) => {
+        const dir = path.join(kitsDir, name);
+        return fs.statSync(dir).isDirectory() && fs.existsSync(path.join(dir, 'package.json'));
+    });
+}
+// Generate one ready-to-serve archive for `kit`: kit source (minus build junk)
+// + installed node_modules + a published-mode package.json, gzipped into the
+// bundled kit dir (cli/kits/<kit>/published-deck.tgz).
+function buildKitArchive(kit, sdkTarball) {
+    const kitDir = path.join(getKitsDir(), kit);
+    if (!fs.existsSync(path.join(kitDir, 'package.json'))) {
+        throw new Error(`Kit "${kit}" has no package.json at ${kitDir}.`);
+    }
+    const stagingRoot = fs.mkdtempSync(path.join(os.tmpdir(), `castle-archive-${kit}-`));
+    const deck = path.join(stagingRoot, 'deck');
+    try {
+        // Same filter the live scaffold uses, plus drop any prior archive.
+        copyKitSource(kitDir, deck, new Set([ARCHIVE_NAME]));
+        // A stale workspace lock would pin file:../../sdk; drop it before install.
+        fs.rmSync(path.join(deck, 'package-lock.json'), { force: true });
+        // Published-mode package.json, but point the sdk at the local tarball so
+        // the install copies our freshly-built sdk into node_modules.
+        const pkgPath = path.join(deck, 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        rewriteKitPackageJson(pkg, kit, PUBLISHED_REFS);
+        pkg.dependencies['castle-web-sdk'] = `file:${toPosixPath(sdkTarball)}`;
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        // Deck deps are pure JS (no native binaries), so this mac-built
+        // node_modules runs as-is on linux/e2b.
+        console.log(`Installing deps for ${kit}...`);
+        execFileSync('npm', ['install', '--no-audit', '--no-fund', '--loglevel=error'], {
+            cwd: deck,
+            stdio: 'inherit',
+        });
+        // Restore the published sdk range (node_modules already holds the real
+        // sdk) and drop the lock pinning the local tarball path.
+        pkg.dependencies['castle-web-sdk'] = `^${PUBLISHED_SDK_VERSION}`;
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        fs.rmSync(path.join(deck, 'package-lock.json'), { force: true });
+        const archivePath = getKitArchivePath(kit);
+        fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+        fs.rmSync(archivePath, { force: true });
+        console.log(`Archiving ${kit} -> ${archivePath}`);
+        execFileSync('tar', ['-czf', archivePath, '-C', deck, '.'], { stdio: 'inherit' });
+        const sizeMb = (fs.statSync(archivePath).size / 1e6).toFixed(1);
+        console.log(`  ${kit} archive: ${sizeMb} MB`);
+    }
+    finally {
+        fs.rmSync(stagingRoot, { recursive: true, force: true });
+    }
+}
+// Generate archives for the given kits (default: every kit under kits/). Builds
+// + packs the sdk once, then archives each kit against that same tarball.
+export function buildKitArchives(kits) {
+    const kitsDir = getKitsDir();
+    const targets = kits ?? discoverKits(kitsDir);
+    if (targets.length === 0) {
+        console.error(`No kits found under ${kitsDir}.`);
+        process.exit(1);
+    }
+    const sdkTarball = packSdk();
+    try {
+        for (const kit of targets)
+            buildKitArchive(kit, sdkTarball);
+    }
+    finally {
+        fs.rmSync(path.dirname(sdkTarball), { recursive: true, force: true });
+    }
+    console.log(`Done. Archived: ${targets.join(', ')}`);
+}

package/dist/index.js

@@ -135,6 +135,14 @@ async function main() {
         case 'login':
             await login();
             break;
+        case 'build-archives': {
+            // Dev/publish tool: generate the prebuilt per-kit deck archives that
+            // `init` extracts in published mode. Run after `npm run build -w cli`.
+            const { buildKitArchives } = await import('./buildArchive.js');
+            const only = getFlagValue('--kit');
+            buildKitArchives(only ? [only] : undefined);
+            break;
+        }
         default:
             usage();
     }

package/dist/init.d.ts

@@ -1,4 +1,22 @@
+export declare const PUBLISHED_SDK_VERSION = "0.4.4";
+export declare const KIT_COPY_EXCLUDE: Set<string>;
+export declare const ARCHIVE_NAME = "published-deck.tgz";
+export declare function getKitArchivePath(kit: string): string;
+export declare function copyKitSource(kitDir: string, dest: string, extraExclude?: Set<string>): void;
+export declare function rewriteKitPackageJson(pkg: {
+    name?: string;
+    dependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+}, name: string, refs: ReturnType<typeof resolveScaffoldRefs>): void;
+declare function resolveScaffoldRefs(): {
+    workspaceMode: boolean;
+    sdkRef: string;
+    cliCommand: string;
+    cliDistAbs: string | null;
+    sdkPathPosix: string | null;
+};
 export declare function init(dir: string, opts?: {
     kit?: string;
     serve?: boolean;
 }): Promise<void>;
+export {};

package/dist/init.js

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync, execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { COMMON_INSTRUCTIONS } from './commonInstructions.js';
@@ -35,10 +35,62 @@ const DEFAULT_KIT = 'basic-2d';
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = '0.4.4';
+export const PUBLISHED_SDK_VERSION = '0.4.4';
 // Never copied into a fresh deck: build/dependency junk, and castle.json (a
 // fresh deck has no deckId until its first save-deck).
-const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git', 'castle.json']);
+export const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git', 'castle.json']);
+// A globally-installed castle-web ships one prebuilt, ready-to-serve archive
+// per kit (kit source + installed node_modules + published-mode package.json),
+// gzipped. `init` in published mode extracts it instead of cp + `npm install`.
+// Lives inside each bundled kit dir (cli/kits/<kit>/), generated by
+// `build-archives` (see buildArchive.ts). Workspace mode never uses it.
+export const ARCHIVE_NAME = 'published-deck.tgz';
+export function getKitArchivePath(kit) {
+    return path.join(getKitsDir(), kit, ARCHIVE_NAME);
+}
+// Copy a framework kit into `dest`, dropping build/dependency junk + castle.json
+// (and any caller-supplied extra names, e.g. a stale archive). Shared by the
+// live scaffold and archive generation so the two stay in sync.
+export function copyKitSource(kitDir, dest, extraExclude) {
+    fs.cpSync(kitDir, dest, {
+        recursive: true,
+        // Keep symlinks verbatim so the kit's AGENTS.md -> CLAUDE.md stays a link.
+        verbatimSymlinks: true,
+        filter: (src) => src === kitDir ||
+            (!KIT_COPY_EXCLUDE.has(path.basename(src)) && !extraExclude?.has(path.basename(src))),
+    });
+}
+// Rewrite a kit's package.json (in place) so the scaffolded deck references the
+// sdk + cli per the resolved mode. Workspace mode points at the local checkout
+// (file: sdk + node <abs cli dist>); published mode points at the registry sdk
+// + the `castle-web` binary. Shared by the live scaffold and archive generation.
+export function rewriteKitPackageJson(pkg, name, refs) {
+    pkg.name = name;
+    const { workspaceMode, sdkRef, cliDistAbs, sdkPathPosix } = refs;
+    if (pkg.dependencies &&
+        typeof pkg.dependencies['castle-web-sdk'] === 'string' &&
+        pkg.dependencies['castle-web-sdk'].startsWith('file:')) {
+        pkg.dependencies['castle-web-sdk'] = sdkRef;
+    }
+    if (!pkg.scripts)
+        return;
+    for (const k of Object.keys(pkg.scripts)) {
+        if (typeof pkg.scripts[k] !== 'string')
+            continue;
+        if (workspaceMode) {
+            pkg.scripts[k] = pkg.scripts[k]
+                .replace(/\.\.\/\.\.\/cli\/dist/g, cliDistAbs)
+                .replace(/\.\.\/\.\.\/sdk/g, sdkPathPosix);
+        }
+        else {
+            // Globally-installed: route through the `castle-web` binary on PATH.
+            pkg.scripts[k] = pkg.scripts[k]
+                .replace(/node\s+\.\.\/\.\.\/cli\/dist\/index\.js/g, 'castle-web')
+                .replace(/await import\((['"])\.\.\/\.\.\/cli\/dist\/bundle\.js\1\)/g, "await import('castle-web-cli/dist/bundle.js')")
+                .replace(/\.\.\/\.\.\/sdk/g, '');
+        }
+    }
+}
 // Resolve how a scaffolded deck should reference the sdk + cli. Both the bare
 // and kit scaffold paths go through here so they stay in sync.
 //   workspace mode (sdk/ sits next to cli/, i.e. running from a checkout):
@@ -127,8 +179,42 @@ function scaffoldBare(projectDir) {
     ensureAgentsSymlink(projectDir);
     fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(makePackageJson(projectDir), null, 2) + '\n');
 }
+// Finalize a deck whose files are already on disk (mirroring scaffoldFromKit's
+// tail): ensure a CLAUDE.md, append the cli-owned common guidance, and create
+// the AGENTS.md symlink. Used by both the cp path and the archive-extract path.
+function finalizeDeckDocs(projectDir) {
+    // Every deck needs a CLAUDE.md so coding agents know how castle-web works.
+    // Keep the kit's own if it ships one; otherwise generate from the upstream.
+    const claudePath = path.join(projectDir, 'CLAUDE.md');
+    if (!fs.existsSync(claudePath)) {
+        fs.writeFileSync(claudePath, makeClaudeMd());
+    }
+    appendCommonInstructions(projectDir);
+    ensureAgentsSymlink(projectDir);
+}
+// Published fast path: extract the prebuilt, ready-to-serve archive into the
+// deck dir (no cp, no `npm install`). The archive carries the kit source +
+// installed node_modules + a published-mode package.json with a generic name;
+// rename it to the deck dir, then run the shared doc finalization.
+function extractKitArchive(archivePath, projectDir) {
+    fs.mkdirSync(projectDir, { recursive: true });
+    execFileSync('tar', ['-xzf', archivePath, '-C', projectDir], { stdio: 'inherit' });
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            pkg.name = path.basename(projectDir);
+            fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        }
+        catch {
+            // archived an unparseable package.json — leave it for the user to fix
+        }
+    }
+    finalizeDeckDocs(projectDir);
+}
 // Copy a framework kit from kits/<kit>/ into the new deck dir, dropping
-// build/dependency junk and castle.json.
+// build/dependency junk and castle.json. Returns whether deps are already
+// installed (true only on the published archive-extract fast path).
 function scaffoldFromKit(kit, projectDir) {
     const kitDir = path.join(getKitsDir(), kit);
     if (!fs.existsSync(kitDir) || !fs.statSync(kitDir).isDirectory()) {
@@ -150,12 +236,17 @@ function scaffoldFromKit(kit, projectDir) {
         console.error('Or use `--kit none` for a bare code-only deck.');
         process.exit(1);
     }
-    fs.cpSync(kitDir, projectDir, {
-        recursive: true,
-        // Keep symlinks verbatim so the kit's AGENTS.md -> CLAUDE.md stays a link.
-        verbatimSymlinks: true,
-        filter: (src) => src === kitDir || !KIT_COPY_EXCLUDE.has(path.basename(src)),
-    });
+    // Published mode (globally-installed castle-web, no sibling sdk/) extracts a
+    // prebuilt archive when one ships for this kit -- skipping cp + `npm install`.
+    // Workspace mode always does the live cp so local sdk edits stay live.
+    const refs = resolveScaffoldRefs();
+    const archivePath = getKitArchivePath(kit);
+    if (!refs.workspaceMode && fs.existsSync(archivePath)) {
+        console.log('Extracting prebuilt deck (deps included)...');
+        extractKitArchive(archivePath, projectDir);
+        return { depsInstalled: true };
+    }
+    copyKitSource(kitDir, projectDir);
     // The kit's package.json carries the kit's name; rename it to the deck dir.
     // Kit-relative refs to `../../sdk` and `../../cli/dist` only resolve when the
     // deck lives at castle-experimental-web/decks/<name>/. Rewrite both to
@@ -165,50 +256,15 @@ function scaffoldFromKit(kit, projectDir) {
     if (fs.existsSync(pkgPath)) {
         try {
             const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-            pkg.name = path.basename(projectDir);
-            // Local-dev paths (`file:../../sdk` / `node ../../cli/dist/index.js`) only
-            // work when the deck lives inside the castle-experimental-web workspace.
-            // For a deck scaffolded from a globally-installed castle-web, rewrite to
-            // the published packages instead. Same workspace-vs-published resolution
-            // the bare scaffold path uses.
-            const { workspaceMode, sdkRef, cliDistAbs, sdkPathPosix } = resolveScaffoldRefs();
-            if (pkg.dependencies &&
-                typeof pkg.dependencies['castle-web-sdk'] === 'string' &&
-                pkg.dependencies['castle-web-sdk'].startsWith('file:')) {
-                pkg.dependencies['castle-web-sdk'] = sdkRef;
-            }
-            if (pkg.scripts) {
-                for (const k of Object.keys(pkg.scripts)) {
-                    if (typeof pkg.scripts[k] !== 'string')
-                        continue;
-                    if (workspaceMode) {
-                        pkg.scripts[k] = pkg.scripts[k]
-                            .replace(/\.\.\/\.\.\/cli\/dist/g, cliDistAbs)
-                            .replace(/\.\.\/\.\.\/sdk/g, sdkPathPosix);
-                    }
-                    else {
-                        // Globally-installed: route through the `castle-web` binary on PATH.
-                        pkg.scripts[k] = pkg.scripts[k]
-                            .replace(/node\s+\.\.\/\.\.\/cli\/dist\/index\.js/g, 'castle-web')
-                            .replace(/await import\((['"])\.\.\/\.\.\/cli\/dist\/bundle\.js\1\)/g, "await import('castle-web-cli/dist/bundle.js')")
-                            .replace(/\.\.\/\.\.\/sdk/g, '');
-                    }
-                }
-            }
+            rewriteKitPackageJson(pkg, path.basename(projectDir), refs);
             fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
         }
         catch {
             // kit shipped an unparseable package.json — leave it for the user to fix
         }
     }
-    // Every deck needs a CLAUDE.md so coding agents know how castle-web works.
-    // Keep the kit's own if it ships one; otherwise generate from the upstream.
-    const claudePath = path.join(projectDir, 'CLAUDE.md');
-    if (!fs.existsSync(claudePath)) {
-        fs.writeFileSync(claudePath, makeClaudeMd());
-    }
-    appendCommonInstructions(projectDir);
-    ensureAgentsSymlink(projectDir);
+    finalizeDeckDocs(projectDir);
+    return { depsInstalled: false };
 }
 export async function init(dir, opts = {}) {
     const projectDir = path.resolve(dir);
@@ -218,11 +274,14 @@ export async function init(dir, opts = {}) {
     }
     const kit = opts.kit ?? DEFAULT_KIT;
     const bare = kit === 'none' || kit === 'bare';
+    // depsInstalled is true only when the published archive fast-path ran, which
+    // already ships node_modules -- so we can skip `npm install` below.
+    let depsInstalled = false;
     if (bare) {
         scaffoldBare(projectDir);
     }
     else {
-        scaffoldFromKit(kit, projectDir);
+        ({ depsInstalled } = scaffoldFromKit(kit, projectDir));
     }
     console.log(`Created project in ${projectDir}/${bare ? '' : ` (from kit "${kit}")`}`);
     // Auto-run npm install + serve so the page is up the moment the
@@ -230,16 +289,21 @@ export async function init(dir, opts = {}) {
     const autoServe = opts.serve !== false;
     if (autoServe) {
         console.log('');
-        console.log('Installing deps + serving (pass --no-serve to skip)...');
-        try {
-            execSync('npm install --no-audit --no-fund --loglevel=error', {
-                cwd: projectDir,
-                stdio: 'inherit',
-            });
+        if (!depsInstalled) {
+            console.log('Installing deps + serving (pass --no-serve to skip)...');
+            try {
+                execSync('npm install --no-audit --no-fund --loglevel=error', {
+                    cwd: projectDir,
+                    stdio: 'inherit',
+                });
+            }
+            catch {
+                console.error('npm install failed; skipping serve. Re-run yourself with `npm install && castle-web serve .` (& in your shell to background it).');
+                return;
+            }
         }
-        catch {
-            console.error('npm install failed; skipping serve. Re-run yourself with `npm install && castle-web serve .` (& in your shell to background it).');
-            return;
+        else {
+            console.log('Serving (deps prebuilt)...');
         }
         // Call serve() with detach so init returns once the server is up. serve()
         // handles the background spawn internally; init doesn't shell out.
@@ -256,6 +320,7 @@ export async function init(dir, opts = {}) {
     console.log('');
     console.log('Next steps:');
     console.log(`  cd ${dir}`);
-    console.log('  npm install');
+    if (!depsInstalled)
+        console.log('  npm install');
     console.log('  castle-web serve .   # & in your shell to background it');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.37",
+  "version": "0.4.38",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"