/** * Dev server-deploy channel — layout + manifest for locally-uploaded root * package closures (ZERO-DEP: node:fs/node:path only, same constraint as * root-state.ts — the baked starter bundles this module). * * `camstack deploy-server` packs every workspace package in the server's * `@camstack/*` closure at one uniform dev version * (`-dev.`) and uploads the tarballs to * `POST /api/server-upload`. The hub stores them under: * * /server-root/dev-uploads// * .tgz one per uploaded package * manifest.json { version, packages: { name → filename } } * * `RootUpdateService.stageAndActivate` detects the dir and stages from these * tarballs (synthetic package.json with `file:` refs + `overrides`) instead * of the npm registry. Everything downstream — probation boot, promote, * rollback — is version-string driven and unchanged; the `-dev.` suffix is * self-describing. * * Spec: docs/superpowers/specs — dev server-deploy channel (2026-07-13). */ import * as fs from 'node:fs' import * as path from 'node:path' export const DEV_UPLOADS_DIRNAME = 'dev-uploads' export const DEV_UPLOAD_MANIFEST_FILE = 'manifest.json' /** Number of dev-uploads entries retained by the promote-time sweep. */ export const DEV_UPLOADS_KEEP_COUNT = 3 /** * Dev-channel version shape: `-dev.`. The suffix * is sortable, self-describing, and can never collide with a published * registry version. The upload route and the staging branch BOTH gate on it. */ const DEV_CHANNEL_VERSION_RE = /-dev\.\d+$/ export function isDevChannelVersion(version: string): boolean { return DEV_CHANNEL_VERSION_RE.test(version) } /** * The `` ordering key of a dev-channel version (or dir name). * Returns null for anything that is not dev-channel shaped — the sweep * treats those as oldest so malformed residue is collected first. */ export function devChannelEpoch(version: string): number | null { const match = /-dev\.(\d+)$/.exec(version) if (match === null) return null const epoch = Number.parseInt(match[1] ?? '', 10) return Number.isNaN(epoch) ? null : epoch } /** `/server-root/dev-uploads` */ export function devUploadsDir(rootDir: string): string { return path.join(rootDir, DEV_UPLOADS_DIRNAME) } /** `/server-root/dev-uploads/` */ export function devUploadVersionDir(rootDir: string, version: string): string { return path.join(devUploadsDir(rootDir), version) } // --------------------------------------------------------------------------- // Manifest IO // --------------------------------------------------------------------------- /** * Written by the hub's `/api/server-upload` route after validating every * tarball; read by the staging branch. Maps each uploaded package NAME to * its tgz FILENAME inside the version dir — staging never has to re-derive * package names from flattened filenames. */ export interface DevUploadManifest { readonly version: string readonly packages: Readonly> } export function devUploadManifestPath(versionDirPath: string): string { return path.join(versionDirPath, DEV_UPLOAD_MANIFEST_FILE) } function isDevUploadManifest(v: unknown): v is DevUploadManifest { if (typeof v !== 'object' || v === null) return false const m = v as Record if (typeof m['version'] !== 'string') return false const packages = m['packages'] if (typeof packages !== 'object' || packages === null || Array.isArray(packages)) return false return Object.values(packages).every((filename) => typeof filename === 'string') } /** Read + validate the manifest. Returns null when missing/corrupt. */ export function readDevUploadManifest(versionDirPath: string): DevUploadManifest | null { try { const raw: unknown = JSON.parse(fs.readFileSync(devUploadManifestPath(versionDirPath), 'utf-8')) return isDevUploadManifest(raw) ? raw : null } catch { return null } } /** Write the manifest atomically (tmp sibling + rename). Creates the dir. */ export function writeDevUploadManifest(versionDirPath: string, manifest: DevUploadManifest): void { fs.mkdirSync(versionDirPath, { recursive: true }) const target = devUploadManifestPath(versionDirPath) const tmp = `${target}.tmp` fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2), 'utf-8') fs.renameSync(tmp, target) }