@happier-dev/stack 0.1.0 → 0.2.0

package/scripts/runtime/shared/runtime_mode.mjs

@@ -0,0 +1,32 @@
+function normalizeRuntimeMode(raw) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (value === 'prefer') return 'prefer';
+  if (value === 'require') return 'require';
+  return 'source';
+}
+
+export function resolveStackRuntimeMode({ argv = [], env = process.env } = {}) {
+  const args = Array.isArray(argv) ? argv : [];
+  const wantsRuntime = args.includes('--runtime');
+  const wantsSource = args.includes('--source');
+
+  if (wantsRuntime && wantsSource) {
+    throw new Error('[runtime] --runtime and --source cannot be used together.');
+  }
+
+  if (wantsRuntime) {
+    return { mode: 'require', source: 'flag' };
+  }
+  if (wantsSource) {
+    return { mode: 'source', source: 'flag' };
+  }
+
+  if (Object.prototype.hasOwnProperty.call(env ?? {}, 'HAPPIER_STACK_RUNTIME_MODE')) {
+    return {
+      mode: normalizeRuntimeMode(env?.HAPPIER_STACK_RUNTIME_MODE),
+      source: 'env',
+    };
+  }
+
+  return { mode: 'source', source: 'default' };
+}

package/scripts/runtime/shared/runtime_mode.test.mjs

@@ -0,0 +1,48 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { resolveStackRuntimeMode } from './runtime_mode.mjs';
+
+test('resolveStackRuntimeMode defaults to source mode', () => {
+  const resolved = resolveStackRuntimeMode({ argv: [], env: {} });
+
+  assert.equal(resolved.mode, 'source');
+  assert.equal(resolved.source, 'default');
+});
+
+test('resolveStackRuntimeMode reads prefer mode from stack env', () => {
+  const resolved = resolveStackRuntimeMode({
+    argv: [],
+    env: { HAPPIER_STACK_RUNTIME_MODE: 'prefer' },
+  });
+
+  assert.equal(resolved.mode, 'prefer');
+  assert.equal(resolved.source, 'env');
+});
+
+test('resolveStackRuntimeMode lets --runtime override source env mode', () => {
+  const resolved = resolveStackRuntimeMode({
+    argv: ['--runtime'],
+    env: { HAPPIER_STACK_RUNTIME_MODE: 'source' },
+  });
+
+  assert.equal(resolved.mode, 'require');
+  assert.equal(resolved.source, 'flag');
+});
+
+test('resolveStackRuntimeMode lets --source override prefer env mode', () => {
+  const resolved = resolveStackRuntimeMode({
+    argv: ['--source'],
+    env: { HAPPIER_STACK_RUNTIME_MODE: 'prefer' },
+  });
+
+  assert.equal(resolved.mode, 'source');
+  assert.equal(resolved.source, 'flag');
+});
+
+test('resolveStackRuntimeMode rejects conflicting launch flags', () => {
+  assert.throws(
+    () => resolveStackRuntimeMode({ argv: ['--runtime', '--source'], env: {} }),
+    /cannot be used together/i,
+  );
+});

package/scripts/runtime/shared/runtime_paths.mjs

@@ -0,0 +1,30 @@
+import { join } from 'node:path';
+
+export function resolveStackArtifactsDir({ stackBaseDir }) {
+  return join(String(stackBaseDir ?? '').trim(), 'artifacts');
+}
+
+export function resolveStackComponentArtifactDir({ stackBaseDir, component, fingerprint }) {
+  return join(resolveStackArtifactsDir({ stackBaseDir }), String(component ?? '').trim(), String(fingerprint ?? '').trim());
+}
+
+export function resolveStackRuntimePaths({ stackBaseDir, snapshotId = '' }) {
+  const runtimeDir = join(String(stackBaseDir ?? '').trim(), 'runtime');
+  const buildsDir = join(runtimeDir, 'builds');
+  const currentDir = join(runtimeDir, 'current');
+  const currentPath = join(runtimeDir, 'current.json');
+  const currentManifestPath = join(currentDir, 'manifest.json');
+  const lockPath = join(runtimeDir, 'build.lock');
+  const snapshotDir = snapshotId ? join(buildsDir, snapshotId) : '';
+
+  return {
+    runtimeDir,
+    buildsDir,
+    currentDir,
+    currentPath,
+    currentManifestPath,
+    lockPath,
+    snapshotDir,
+    manifestPath: snapshotDir ? join(snapshotDir, 'manifest.json') : '',
+  };
+}

package/scripts/runtime/shared/runtime_paths.test.mjs

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  resolveStackArtifactsDir,
+  resolveStackComponentArtifactDir,
+  resolveStackRuntimePaths,
+} from './runtime_paths.mjs';
+
+test('resolveStackArtifactsDir places artifacts under the stack base dir', () => {
+  const dir = resolveStackArtifactsDir({ stackBaseDir: '/tmp/happier/stacks/prod-dev' });
+
+  assert.equal(dir, '/tmp/happier/stacks/prod-dev/artifacts');
+});
+
+test('resolveStackComponentArtifactDir scopes artifacts by component and fingerprint', () => {
+  const dir = resolveStackComponentArtifactDir({
+    stackBaseDir: '/tmp/happier/stacks/prod-dev',
+    component: 'server',
+    fingerprint: 'abc123',
+  });
+
+  assert.equal(dir, '/tmp/happier/stacks/prod-dev/artifacts/server/abc123');
+});
+
+test('resolveStackRuntimePaths exposes build and activation locations', () => {
+  const paths = resolveStackRuntimePaths({
+    stackBaseDir: '/tmp/happier/stacks/prod-dev',
+    snapshotId: 'snap-1',
+  });
+
+  assert.deepEqual(paths, {
+    runtimeDir: '/tmp/happier/stacks/prod-dev/runtime',
+    buildsDir: '/tmp/happier/stacks/prod-dev/runtime/builds',
+    currentDir: '/tmp/happier/stacks/prod-dev/runtime/current',
+    currentPath: '/tmp/happier/stacks/prod-dev/runtime/current.json',
+    currentManifestPath: '/tmp/happier/stacks/prod-dev/runtime/current/manifest.json',
+    lockPath: '/tmp/happier/stacks/prod-dev/runtime/build.lock',
+    snapshotDir: '/tmp/happier/stacks/prod-dev/runtime/builds/snap-1',
+    manifestPath: '/tmp/happier/stacks/prod-dev/runtime/builds/snap-1/manifest.json',
+  });
+});

package/scripts/runtime_activate.mjs

@@ -0,0 +1,135 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getRootDir, resolveStackBaseDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { collectBuildSourceMetadata } from './build/collect_build_source_metadata.mjs';
+import { activateRuntimeSnapshot } from './build/activate_runtime_snapshot.mjs';
+import { resolveLatestComponentArtifact } from './build/resolve_latest_component_artifact.mjs';
+import { acquireRuntimeBuildLock } from './build/runtime_build_lock.mjs';
+import { resolveRuntimeRetentionPolicy } from './build/runtime_retention.mjs';
+import { createRuntimeFingerprint } from './runtime/shared/runtime_fingerprint.mjs';
+import { resolveStackRuntimePaths } from './runtime/shared/runtime_paths.mjs';
+import { inspectActiveRuntimeSnapshot } from './runtime/launch/inspectActiveRuntimeSnapshot.mjs';
+import { ensureStackRuntimeModePrefer } from './runtime/shared/ensureStackRuntimeModePrefer.mjs';
+
+function resolveSelectedComponents(flags) {
+  const explicit = {
+    web: flags.has('--web'),
+    server: flags.has('--server'),
+    daemon: flags.has('--daemon'),
+  };
+  if (flags.has('--all') || !Object.values(explicit).some(Boolean)) {
+    return { web: true, server: true, daemon: true };
+  }
+  return explicit;
+}
+
+function assertNamedStack(env) {
+  const stackName = String(env.HAPPIER_STACK_STACK ?? '').trim() || 'main';
+  if (stackName === 'main') {
+    throw new Error('[runtime] partial runtime activation is supported for named stacks only in v1.');
+  }
+  return stackName;
+}
+
+function createSnapshotId({ sourceMetadata, componentFingerprints }) {
+  return createRuntimeFingerprint({
+    repoDir: sourceMetadata.repoDir,
+    commitSha: sourceMetadata.commitSha,
+    dirtyHash: sourceMetadata.dirtyHash,
+    serverComponent: sourceMetadata.serverComponent,
+    dbProvider: sourceMetadata.dbProvider,
+    components: ['runtime-snapshot'],
+    buildInputs: Object.entries(componentFingerprints)
+      .filter(([, artifactFingerprint]) => String(artifactFingerprint ?? '').trim())
+      .map(([component, artifactFingerprint]) => `${component}=${artifactFingerprint}`),
+  });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { flags: ['--web', '--server', '--daemon', '--all'], json: true },
+      text: [
+        '[runtime] usage:',
+        '  hstack stack runtime <name> activate [--web|--server|--daemon|--all] [--json]',
+        '',
+        'note:',
+        '  Reuses the current runtime snapshot for unselected components.',
+        '  With no component flags, activates all components from the latest available artifacts.',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const stackName = assertNamedStack(process.env);
+  const selectedComponents = resolveSelectedComponents(flags);
+  const sourceMetadata = await collectBuildSourceMetadata({ rootDir, env: process.env });
+  const retentionPolicy = resolveRuntimeRetentionPolicy({ env: process.env });
+  const { baseDir: stackBaseDir } = resolveStackBaseDir(stackName, process.env);
+  const runtimePaths = resolveStackRuntimePaths({ stackBaseDir });
+  const releaseBuildLock = await acquireRuntimeBuildLock({ lockPath: runtimePaths.lockPath });
+
+  try {
+    const currentInspection = await inspectActiveRuntimeSnapshot({ stackBaseDir });
+    const artifacts = {};
+    for (const component of ['web', 'server', 'daemon']) {
+      if (!selectedComponents[component]) continue;
+      const artifact = await resolveLatestComponentArtifact({ stackBaseDir, component });
+      if (!artifact) {
+        throw new Error(`[runtime] no ${component} artifact is available for activation. Build it first.`);
+      }
+      artifacts[component] = artifact;
+    }
+
+    const componentFingerprints = {
+      web: artifacts.web?.manifest?.artifactFingerprint ?? currentInspection.manifest?.components?.web?.artifactFingerprint ?? '',
+      server: artifacts.server?.manifest?.artifactFingerprint ?? currentInspection.manifest?.components?.server?.artifactFingerprint ?? '',
+      daemon: artifacts.daemon?.manifest?.artifactFingerprint ?? currentInspection.manifest?.components?.daemon?.artifactFingerprint ?? '',
+    };
+    const snapshotId = createSnapshotId({ sourceMetadata, componentFingerprints });
+    const runtime = await activateRuntimeSnapshot({
+      stackBaseDir,
+      snapshotId,
+      sourceMetadata,
+      artifacts,
+      runtimeSnapshotKeepCount: retentionPolicy.runtimeSnapshotKeepCount,
+    });
+
+    const { envPath } = resolveStackEnvPath(stackName, process.env);
+    await ensureStackRuntimeModePrefer({ envPath });
+
+    printResult({
+      json,
+      data: {
+        ok: true,
+        stackName,
+        activatedComponents: Object.keys(selectedComponents).filter((component) => selectedComponents[component]),
+        runtime,
+      },
+      text: [
+        `[runtime] activated ${stackName}`,
+        ...Object.keys(selectedComponents)
+          .filter((component) => selectedComponents[component])
+          .map((component) => `[runtime] ${component}: updated`),
+        `[runtime] snapshot: ${runtime.snapshotPath}`,
+      ].join('\n'),
+    });
+  } finally {
+    await releaseBuildLock();
+  }
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error('[runtime] failed:', message);
+  if (process.env.DEBUG && error instanceof Error && error.stack) {
+    console.error(error.stack);
+  }
+  process.exit(1);
+});

package/scripts/sandbox_workspace_override.test.mjs

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function runCapture(cmd, args, { cwd, env } = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const proc = spawn(cmd, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += String(d)));
+    proc.stderr.on('data', (d) => (stderr += String(d)));
+    proc.on('error', rejectPromise);
+    proc.on('exit', (code) => resolvePromise({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+test('sandbox mode honors HAPPIER_STACK_SANDBOX_WORKSPACE_DIR override', async (t) => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const bin = join(rootDir, 'bin', 'hstack.mjs');
+
+  const sandboxDir = await mkdtemp(join(tmpdir(), 'hstack-sandbox-ws-'));
+  const workspaceDir = await mkdtemp(join(tmpdir(), 'hstack-ws-cache-'));
+  t.after(async () => {
+    await rm(sandboxDir, { recursive: true, force: true });
+    await rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  const env = {
+    ...process.env,
+    HAPPIER_STACK_SANDBOX_WORKSPACE_DIR: workspaceDir,
+  };
+
+  const res = await runCapture(process.execPath, [bin, '--sandbox-dir', sandboxDir, 'where', '--json'], { cwd: rootDir, env });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const data = JSON.parse(res.stdout);
+  assert.equal(resolve(data.workspaceDir), resolve(workspaceDir));
+  assert.equal(resolve(data.checkouts.main), resolve(join(workspaceDir, 'main')));
+  assert.equal(resolve(data.pmCacheBaseDir), resolve(join(workspaceDir, '.hstack-cache', 'pm')));
+  assert.equal(resolve(data.expoSharedTmpDirBaseDir), resolve(join(workspaceDir, '.hstack-cache', 'expo')));
+  assert.equal(resolve(data.expoSharedTmpDirKey), resolve(workspaceDir));
+});

package/scripts/self.mjs

@@ -4,7 +4,9 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
+import { normalizePublicReleaseRingId } from '@happier-dev/release-runtime/releaseRings';
 import { compareVersions, installRuntimeFromNpm, readNpmDistTagVersion, resolveNpmPackageNameOverride } from '@happier-dev/cli-common/update';
+import { installVersionedPayload } from '@happier-dev/cli-common/firstPartyRuntime';
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { pathExists } from './utils/fs/fs.mjs';
@@ -67,8 +69,13 @@ async function getInvokerVersion({ rootDir }) {
 
 function parseSelfChannel({ flags, kv }) {
   if (flags.has('--preview')) return 'preview';
+  if (flags.has('--dev')) return 'publicdev';
   const raw = String(kv.get('--channel') ?? '').trim();
-  return raw === 'preview' ? 'preview' : 'stable';
+  return normalizePublicReleaseRingId(raw) || 'stable';
+}
+
+function resolveStackSelfNpmDistTag(channel) {
+  return channel === 'stable' ? 'latest' : 'next';
 }
 
 async function fetchLatestVersion({ packageName, distTag, cwd }) {
@@ -82,7 +89,7 @@ async function cmdStatus({ rootDir, argv }) {
   const json = wantsJson(argv, { flags });
   const doCheck = !flags.has('--no-check');
   const channel = parseSelfChannel({ flags, kv: kvArgs });
-  const distTag = channel === 'preview' ? 'next' : 'latest';
+  const distTag = resolveStackSelfNpmDistTag(channel);
 
   const { updateJson, cacheDir } = cachePaths();
   const invoker = await readJsonIfExists(join(rootDir, 'package.json'), { defaultValue: null });
@@ -162,7 +169,7 @@ async function cmdUpdate({ rootDir, argv }) {
     fallback: String(invoker?.name ?? '').trim(),
   });
   if (!pkgName) throw new Error('[self] unable to resolve package name (missing package.json name)');
-  const spec = to ? `${pkgName}@${to}` : `${pkgName}@${channel === 'preview' ? 'next' : 'latest'}`;
+  const spec = to ? `${pkgName}@${to}` : `${pkgName}@${resolveStackSelfNpmDistTag(channel)}`;
 
   // Ensure runtime dir exists.
   await mkdir(runtimeDir, { recursive: true });
@@ -190,7 +197,7 @@ async function cmdUpdate({ rootDir, argv }) {
 
   // Refresh cache best-effort.
   try {
-    const latest = await fetchLatestVersion({ packageName: pkgName, distTag: channel === 'preview' ? 'next' : 'latest', cwd: rootDir });
+    const latest = await fetchLatestVersion({ packageName: pkgName, distTag: resolveStackSelfNpmDistTag(channel), cwd: rootDir });
     const runtimeVersion = await getRuntimeInstalledVersion();
     const invokerVersion = await getInvokerVersion({ rootDir });
     const current = runtimeVersion || invokerVersion;
@@ -223,7 +230,7 @@ async function cmdCheck({ rootDir, argv }) {
   const json = wantsJson(argv, { flags });
   const quiet = flags.has('--quiet');
   const channel = parseSelfChannel({ flags, kv: kvArgs });
-  const distTag = channel === 'preview' ? 'next' : 'latest';
+  const distTag = resolveStackSelfNpmDistTag(channel);
 
   const { updateJson, cacheDir } = cachePaths();
   const runtimeVersion = await getRuntimeInstalledVersion();
@@ -291,6 +298,21 @@ function resolveCliRootCandidate({ rootDir, target }) {
   return abs;
 }
 
+function readCliOptionValue(argv, name) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] ?? '';
+    if (arg === name) {
+      const next = String(args[i + 1] ?? '').trim();
+      return next || '';
+    }
+    if (arg.startsWith(`${name}=`)) {
+      return String(arg.slice(`${name}=`.length)).trim();
+    }
+  }
+  return '';
+}
+
 async function cmdUseCli({ rootDir, argv }) {
   const { flags, kv } = parseArgs(argv);
   const json = wantsJson(argv, { flags });
@@ -385,6 +407,35 @@ async function cmdUseCli({ rootDir, argv }) {
   });
 }
 
+async function cmdInternalInstallPayload({ argv }) {
+  const componentId = readCliOptionValue(argv, '--component');
+  const payloadRoot = readCliOptionValue(argv, '--payload-root');
+  const versionId = readCliOptionValue(argv, '--version');
+  const rawChannel = readCliOptionValue(argv, '--channel');
+  const channel = rawChannel ? normalizePublicReleaseRingId(rawChannel) : 'stable';
+
+  if (componentId !== 'hstack') {
+    throw new Error('--component must be hstack');
+  }
+  if (!payloadRoot) {
+    throw new Error('--payload-root is required');
+  }
+  if (!versionId) {
+    throw new Error('--version is required');
+  }
+  if (rawChannel && !channel) {
+    throw new Error(`invalid --channel value: ${rawChannel}`);
+  }
+
+  await installVersionedPayload({
+    componentId: 'hstack',
+    versionId,
+    payloadRoot,
+    channel: channel || 'stable',
+    processEnv: process.env,
+  });
+}
+
 async function main() {
   const rootDir = getRootDir(import.meta.url);
   const argv = process.argv.slice(2);
@@ -397,9 +448,9 @@ async function main() {
   const wantsHelpFlag = wantsHelp(helpScopeArgv, { flags });
   const json = wantsJson(helpScopeArgv, { flags });
   const usageByCmd = new Map([
-    ['status', 'hstack self status [--preview|--channel=preview] [--no-check] [--json]'],
-    ['update', 'hstack self update [--preview|--channel=preview] [--to=<version>] [--json]'],
-    ['check', 'hstack self check [--preview|--channel=preview] [--quiet] [--json]'],
+    ['status', 'hstack self status [--preview|--dev|--channel=<preview|dev>] [--no-check] [--json]'],
+    ['update', 'hstack self update [--preview|--dev|--channel=<preview|dev>] [--to=<version>] [--json]'],
+    ['check', 'hstack self check [--preview|--dev|--channel=<preview|dev>] [--quiet] [--json]'],
     ['use-cli', 'hstack self use-cli default|main|dev|/abs/path/to/apps/stack [--json]'],
   ]);
 
@@ -418,20 +469,21 @@ async function main() {
   if (wantsHelpFlag || cmd === 'help') {
     printResult({
       json,
-      data: { commands: ['status', 'update', 'check', 'use-cli'], flags: ['--preview', '--channel=preview', '--no-check', '--to=<version>', '--quiet'] },
+      data: { commands: ['status', 'update', 'check', 'use-cli'], flags: ['--preview', '--dev', '--channel=<preview|dev>', '--no-check', '--to=<version>', '--quiet'] },
       text: [
         banner('self', { subtitle: 'Runtime install + self-update.' }),
         '',
         sectionTitle('usage:'),
-        `  ${cyan('hstack self')} status [--preview|--channel=preview] [--no-check] [--json]`,
-        `  ${cyan('hstack self')} update [--preview|--channel=preview] [--to=<version>] [--json]`,
-        `  ${cyan('hstack self')} check [--preview|--channel=preview] [--quiet] [--json]`,
+        `  ${cyan('hstack self')} status [--preview|--dev|--channel=<preview|dev>] [--no-check] [--json]`,
+        `  ${cyan('hstack self')} update [--preview|--dev|--channel=<preview|dev>] [--to=<version>] [--json]`,
+        `  ${cyan('hstack self')} check [--preview|--dev|--channel=<preview|dev>] [--quiet] [--json]`,
         `  ${cyan('hstack self')} use-cli default|main|dev|/abs/path/to/apps/stack [--json]`,
         '',
         sectionTitle('channels:'),
         bullets([
           kv('stable:', dim('npm dist-tag latest')),
           kv('preview:', dim('npm dist-tag next')),
+          kv('dev:', dim('npm dist-tag next')),
         ]),
       ].join('\n'),
     });
@@ -454,6 +506,10 @@ async function main() {
     await cmdUseCli({ rootDir, argv });
     return;
   }
+  if (cmd === '__install-payload') {
+    await cmdInternalInstallPayload({ argv });
+    return;
+  }
 
   throw new Error(`[self] unknown command: ${cmd}`);
 }

package/scripts/self_host/findExtractedExecutableByName.mjs

@@ -0,0 +1,20 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export async function findExtractedExecutableByName(rootDir, binaryName) {
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await findExtractedExecutableByName(fullPath, binaryName);
+      if (nested) return nested;
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (entry.name !== binaryName) continue;
+    const info = await stat(fullPath);
+    if (process.platform === 'win32') return fullPath;
+    if ((info.mode & 0o111) !== 0) return fullPath;
+  }
+  return '';
+}