@mondaydotcomorg/z2h-cli 0.1.0 → 0.2.0

package/dist/util/workspace.d.ts

@@ -0,0 +1,20 @@
+export declare const WORKSPACE_DIR_NAME = "zth-projects";
+export declare const WORKSPACE_MARKER_FIELD = "z2hWorkspace";
+/**
+ * The Z2H workspace home is hardcoded to `~/zth-projects/` for users.
+ * Tests override via the `Z2H_WORKSPACE_HOME` env var so they can use a
+ * tmp dir without touching the user's real home.
+ */
+export declare function getWorkspaceHome(): string;
+/**
+ * Returns true iff `<dir>/package.json` exists and has `"z2hWorkspace": true`.
+ * Any read or parse error returns false (defensive — callers route to a
+ * helpful message via assertWorkspace).
+ */
+export declare function isZ2hWorkspace(dir: string): Promise<boolean>;
+/**
+ * Resolves to the workspace home path if the marker is present; otherwise
+ * throws an Error pointing the user at `z2h-cli create-workspace`.
+ */
+export declare function assertWorkspace(): Promise<string>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/util/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/util/workspace.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AACjD,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAMD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWlE;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CASvD"}

package/dist/util/workspace.js

@@ -0,0 +1,57 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const path = require('node:path');
+const os = require('node:os');
+const fsExtra = require('fs-extra');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const path__default = /*#__PURE__*/_interopDefault(path);
+const os__default = /*#__PURE__*/_interopDefault(os);
+
+const WORKSPACE_DIR_NAME = 'zth-projects';
+const WORKSPACE_MARKER_FIELD = 'z2hWorkspace';
+/**
+ * The Z2H workspace home is hardcoded to `~/zth-projects/` for users.
+ * Tests override via the `Z2H_WORKSPACE_HOME` env var so they can use a
+ * tmp dir without touching the user's real home.
+ */
+function getWorkspaceHome() {
+    return process.env.Z2H_WORKSPACE_HOME ?? path__default.default.join(os__default.default.homedir(), WORKSPACE_DIR_NAME);
+}
+/**
+ * Returns true iff `<dir>/package.json` exists and has `"z2hWorkspace": true`.
+ * Any read or parse error returns false (defensive — callers route to a
+ * helpful message via assertWorkspace).
+ */
+async function isZ2hWorkspace(dir) {
+    const pkgPath = path__default.default.join(dir, 'package.json');
+    if (!(await fsExtra.pathExists(pkgPath))) {
+        return false;
+    }
+    try {
+        const pkg = (await fsExtra.readJson(pkgPath));
+        return pkg[WORKSPACE_MARKER_FIELD] === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves to the workspace home path if the marker is present; otherwise
+ * throws an Error pointing the user at `z2h-cli create-workspace`.
+ */
+async function assertWorkspace() {
+    const home = getWorkspaceHome();
+    if (await isZ2hWorkspace(home)) {
+        return home;
+    }
+    throw new Error(`No Z2H workspace at ${home}. Run "z2h-cli create-workspace" first ` +
+        `(or set Z2H_WORKSPACE_HOME if you keep the workspace elsewhere).`);
+}
+
+exports.WORKSPACE_DIR_NAME = WORKSPACE_DIR_NAME;
+exports.WORKSPACE_MARKER_FIELD = WORKSPACE_MARKER_FIELD;
+exports.assertWorkspace = assertWorkspace;
+exports.getWorkspaceHome = getWorkspaceHome;
+exports.isZ2hWorkspace = isZ2hWorkspace;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,7 +20,8 @@
     ]
   },
   "scripts": {
-    "test": "echo noop",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "trident-library lint",
     "build": "trident-library build",
     "watch": "trident-library build -w"
@@ -46,7 +47,8 @@
     "@types/fs-extra": "^11.0.4",
     "@types/mime-types": "^2.1.4",
     "@types/node": "^22.19.0",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.4"
   },
   "repository": {
     "type": "git",

package/src/commands/__tests__/create-workspace.test.ts

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, writeJson, readJson, ensureDir, pathExists } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { execa } from 'execa';
+import { createWorkspaceCommand } from '../create-workspace';
+
+// Mock execa so `yarn install` doesn't actually run.
+vi.mock('execa', () => ({
+  execa: vi.fn().mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 }),
+}));
+
+describe('create-workspace', () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-cw-'));
+    process.env.Z2H_WORKSPACE_HOME = tmp;
+    vi.mocked(execa).mockClear();
+    // After mkdtemp the dir exists and is empty; we want absent for the
+    // "happy path" tests, so remove it.
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  afterEach(async () => {
+    delete process.env.Z2H_WORKSPACE_HOME;
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('creates package.json with the marker, gitignore, README, then runs yarn install', async () => {
+    await createWorkspaceCommand({});
+
+    const pkgPath = path.join(tmp, 'package.json');
+    expect(await pathExists(pkgPath)).toBe(true);
+    const pkg = await readJson(pkgPath);
+    expect(pkg.z2hWorkspace).toBe(true);
+    expect(pkg.workspaces).toEqual(['*', '*/.zth']);
+    expect(pkg.private).toBe(true);
+    expect(pkg.dependencies).toBeDefined();
+    expect(pkg.devDependencies).toBeDefined();
+
+    expect(await pathExists(path.join(tmp, '.gitignore'))).toBe(true);
+    expect(await pathExists(path.join(tmp, '.yarnrc.yml'))).toBe(true);
+    expect(await pathExists(path.join(tmp, '.nvmrc'))).toBe(true);
+    expect(await pathExists(path.join(tmp, '.npmrc'))).toBe(true);
+    expect(await pathExists(path.join(tmp, 'README.md'))).toBe(true);
+
+    expect(execa).toHaveBeenCalledWith(
+      'yarn',
+      expect.arrayContaining(['install']),
+      expect.objectContaining({ cwd: tmp })
+    );
+  });
+
+  it('refuses if the target dir is non-empty', async () => {
+    await ensureDir(tmp);
+    await writeJson(path.join(tmp, 'somefile.json'), { hello: 'world' });
+
+    await expect(createWorkspaceCommand({})).rejects.toThrow(/non-empty/);
+    expect(execa).not.toHaveBeenCalled();
+  });
+
+  it('substitutes the current z2h-cli version into the workspace template', async () => {
+    await createWorkspaceCommand({});
+
+    const pkg = await readJson(path.join(tmp, 'package.json'));
+    const cliDep = pkg.devDependencies['@mondaydotcomorg/z2h-cli'];
+    expect(cliDep).toBeTruthy();
+    expect(cliDep).not.toBe('__Z2H_CLI_VERSION__'); // should be substituted
+  });
+
+  it('ships the yarn berry release inline so any `yarn` invocation runs 4.x without corepack', async () => {
+    await createWorkspaceCommand({});
+
+    expect(await pathExists(path.join(tmp, '.yarn', 'releases', 'yarn-4.5.1.cjs'))).toBe(true);
+  });
+});

package/src/commands/__tests__/create.test.ts

@@ -0,0 +1,114 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, writeJson, readJson, ensureDir, pathExists, writeFile } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { execa } from 'execa';
+import { createCommand } from '../create';
+import * as manifest from '../../util/manifest';
+
+vi.mock('execa', () => ({
+  execa: vi.fn().mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 }),
+}));
+
+vi.spyOn(manifest, 'readManifest').mockResolvedValue({});
+
+async function makeWorkspace(tmp: string): Promise<void> {
+  await ensureDir(tmp);
+  await writeJson(path.join(tmp, 'package.json'), {
+    name: '@mondaydotcomorg/zth-projects-workspace',
+    private: true,
+    z2hWorkspace: true,
+    workspaces: ['*', '*/.zth'],
+  });
+}
+
+describe('create', () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-c-'));
+    process.env.Z2H_WORKSPACE_HOME = tmp;
+    vi.mocked(execa).mockClear();
+  });
+
+  afterEach(async () => {
+    delete process.env.Z2H_WORKSPACE_HOME;
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('refuses when there is no workspace marker', async () => {
+    await expect(createCommand('demo-app', {})).rejects.toThrow(/create-workspace/);
+    expect(execa).not.toHaveBeenCalled();
+  });
+
+  it('rejects invalid app names', async () => {
+    await makeWorkspace(tmp);
+    await expect(createCommand('Invalid_Name', {})).rejects.toThrow(/lowercase kebab-case/);
+    await expect(createCommand('1starts-with-digit', {})).rejects.toThrow(/lowercase kebab-case/);
+  });
+
+  it('refuses when the target app dir already exists and is non-empty', async () => {
+    await makeWorkspace(tmp);
+    const appDir = path.join(tmp, 'demo-app');
+    await ensureDir(appDir);
+    await writeFile(path.join(appDir, 'something.txt'), 'hi');
+    await expect(createCommand('demo-app', {})).rejects.toThrow(/non-empty/);
+  });
+
+  it('scaffolds an app with the default React template', async () => {
+    await makeWorkspace(tmp);
+    await createCommand('demo-app', {});
+
+    const appDir = path.join(tmp, 'demo-app');
+    expect(await pathExists(path.join(appDir, 'package.json'))).toBe(true);
+    expect(await pathExists(path.join(appDir, 'src', 'index.tsx'))).toBe(true);
+    expect(await pathExists(path.join(appDir, '.gitignore'))).toBe(true);
+    expect(await pathExists(path.join(appDir, '.claude', 'settings.json'))).toBe(true);
+    expect(await pathExists(path.join(appDir, 'CLAUDE.md'))).toBe(true);
+
+    const pkg = await readJson(path.join(appDir, 'package.json'));
+    expect(pkg.name).toBe('demo-app');
+    expect(pkg.private).toBe(true);
+    expect(pkg.scripts.start).toBe('z2h-cli dev');
+
+    const indexSrc = (await import('node:fs/promises')).readFile;
+    const content = await indexSrc(path.join(appDir, 'src', 'index.tsx'), 'utf8');
+    expect(content).toContain('export default function DemoApp()');
+    expect(content).not.toContain('__APP_COMPONENT__');
+
+    expect(execa).toHaveBeenCalledWith(
+      'yarn',
+      expect.arrayContaining(['install']),
+      expect.objectContaining({ cwd: tmp })
+    );
+  });
+
+  it('scaffolds an html-embed app and copies the html file', async () => {
+    await makeWorkspace(tmp);
+    const htmlPath = path.join(tmp, 'page.html');
+    await writeFile(htmlPath, '<html><body>Hi</body></html>');
+
+    await createCommand('html-app', { template: 'html-embed', htmlFile: htmlPath });
+
+    const appDir = path.join(tmp, 'html-app');
+    expect(await pathExists(path.join(appDir, 'src', 'page.html'))).toBe(true);
+    const indexContent = await (
+      await import('node:fs/promises')
+    ).readFile(path.join(appDir, 'src', 'index.tsx'), 'utf8');
+    expect(indexContent).toContain("import pageUrl from './page.html?url'");
+    expect(indexContent).toContain('export default function HtmlApp()');
+  });
+
+  it('rejects unknown templates', async () => {
+    await makeWorkspace(tmp);
+    await expect(createCommand('demo', { template: 'nonexistent' })).rejects.toThrow(/unknown template/i);
+  });
+
+  it('rejects --html-file when the file does not exist', async () => {
+    await makeWorkspace(tmp);
+    await expect(createCommand('demo', { template: 'html-embed', htmlFile: '/no/such/file.html' })).rejects.toThrow(
+      /html file/i
+    );
+  });
+});

package/src/commands/build.ts

@@ -5,6 +5,7 @@ import { prepareShadow } from '../shadow/prepare';
 
 export interface BuildOptions {
   json?: boolean;
+  publicUrl?: string;
 }
 
 export async function buildCommand(opts: BuildOptions): Promise<void> {
@@ -27,7 +28,11 @@ export async function buildCommand(opts: BuildOptions): Promise<void> {
   });
 
   info(`building "${ctx.appName}" via trident`);
-  await execa('yarn', ['build'], { cwd: ctx.paths.shadowDir, stdio: 'inherit' });
+  await execa('yarn', ['build'], {
+    cwd: ctx.paths.shadowDir,
+    stdio: 'inherit',
+    env: { ...process.env, ...(opts.publicUrl ? { PUBLIC_URL: opts.publicUrl } : {}) },
+  });
 
   if (!(await pathExists(ctx.paths.shadowBuild))) {
     throw new Error(`Expected build output at ${ctx.paths.shadowBuild} — not found.`);

package/src/commands/create-workspace.ts

@@ -0,0 +1,86 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { ensureDir, readJson, writeFile, pathExists, readdir, copy } from 'fs-extra';
+import { execa } from 'execa';
+import { info, output, setOutputMode } from '../util/logger';
+import { getWorkspaceHome } from '../util/workspace';
+import { getTemplatesDir, renderTemplate } from '../util/templates';
+
+export interface CreateWorkspaceOptions {
+  json?: boolean;
+}
+
+/**
+ * Read the current z2h-cli version from its own package.json — the version
+ * that gets pinned into the workspace's devDependencies. That way the
+ * workspace's `@mondaydotcomorg/z2h-cli` always matches the version that
+ * bootstrapped it.
+ */
+async function readCurrentCliVersion(): Promise<string> {
+  // util/templates.ts already locates `<package-root>/src/templates`. The
+  // package's own package.json sits two levels above templates/.
+  const templatesDir = getTemplatesDir();
+  const pkgPath = path.resolve(templatesDir, '..', '..', 'package.json');
+  const pkg = (await readJson(pkgPath)) as { version: string };
+  return `^${pkg.version}`;
+}
+
+export async function createWorkspaceCommand(opts: CreateWorkspaceOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  const home = getWorkspaceHome();
+  const templatesDir = getTemplatesDir();
+  const wsTemplatesDir = path.join(templatesDir, 'workspace');
+
+  // Refuse non-empty target.
+  if (await pathExists(home)) {
+    const entries = await readdir(home);
+    if (entries.length > 0) {
+      throw new Error(`${home} is non-empty. Wipe it before running create-workspace.`);
+    }
+  } else {
+    await ensureDir(home);
+  }
+
+  const [cliVersion, pkgRaw] = await Promise.all([
+    readCurrentCliVersion(),
+    readFile(path.join(wsTemplatesDir, 'package.json.tmpl'), 'utf8'),
+  ]);
+
+  // Sources have plain names (gitignore, yarnrc.yml, nvmrc, npmrc) so they
+  // aren't interpreted as the active config files of *this* package; we
+  // rename to dotfiles at the destination.
+  //
+  // Yarn berry ships inline at .yarn/releases/. The workspace's .yarnrc.yml
+  // sets `yarnPath` to point here, so any `yarn` invocation (system classic
+  // or otherwise) reads the rc, delegates to this binary, and runs as 4.5.1
+  // — no corepack, no global pin needed. Mirrors how bigbrain-z2h ships its
+  // own yarn release.
+  await Promise.all([
+    writeFile(path.join(home, 'package.json'), renderTemplate(pkgRaw, { __Z2H_CLI_VERSION__: cliVersion })),
+    copy(path.join(wsTemplatesDir, 'gitignore'), path.join(home, '.gitignore')),
+    copy(path.join(wsTemplatesDir, 'yarnrc.yml'), path.join(home, '.yarnrc.yml')),
+    copy(path.join(wsTemplatesDir, 'yarnlock'), path.join(home, 'yarn.lock')),
+    copy(path.join(wsTemplatesDir, 'nvmrc'), path.join(home, '.nvmrc')),
+    copy(path.join(wsTemplatesDir, 'npmrc'), path.join(home, '.npmrc')),
+    copy(path.join(wsTemplatesDir, 'README.md'), path.join(home, 'README.md')),
+    copy(
+      path.join(wsTemplatesDir, 'yarn-releases', 'yarn-4.5.1.cjs'),
+      path.join(home, '.yarn', 'releases', 'yarn-4.5.1.cjs')
+    ),
+  ]);
+
+  info(`bootstrapping workspace at ${home}`);
+  await execa('yarn', ['install'], {
+    cwd: home,
+    stdio: 'inherit',
+  });
+
+  output(`[z2h-cli] workspace ready at ${home}`, {
+    ok: true,
+    workspace: home,
+    z2hCliVersion: cliVersion,
+  });
+}

package/src/commands/create.ts

@@ -0,0 +1,121 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { ensureDir, pathExists, readdir, writeFile, copy } from 'fs-extra';
+import { execa } from 'execa';
+import { info, output, setOutputMode } from '../util/logger';
+import { assertWorkspace } from '../util/workspace';
+import { getTemplatesDir, renderTemplate, APP_TEMPLATES, type AppTemplate } from '../util/templates';
+import { readManifest } from '../util/manifest';
+import { mfAppName } from '../util/app-name';
+
+export interface CreateOptions {
+  template?: string;
+  htmlFile?: string;
+  json?: boolean;
+}
+
+const APP_NAME_RE = /^[a-z][a-z0-9-]{1,49}$/;
+
+/**
+ * Convert kebab-case to PascalCase. `demo-app` → `DemoApp`.
+ */
+function pascalCase(input: string): string {
+  return input
+    .split('-')
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * Returns true iff `dir` either does not exist or is an empty directory.
+ */
+async function isDirEmpty(dir: string): Promise<boolean> {
+  if (!(await pathExists(dir))) {
+    return true;
+  }
+  const entries = await readdir(dir);
+  return entries.length === 0;
+}
+
+export async function createCommand(appName: string, opts: CreateOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  // Validate workspace.
+  const workspace = await assertWorkspace();
+
+  // Validate app name.
+  if (!APP_NAME_RE.test(appName)) {
+    throw new Error(
+      `App name "${appName}" is invalid. Use lowercase kebab-case (a-z, 0-9, -), ` +
+        `2-50 chars, starting with a letter.`
+    );
+  }
+
+  // Resolve template.
+  // `--html-file` implies `--template html-embed` unless the user already picked one.
+  const template: AppTemplate = (opts.template ?? (opts.htmlFile ? 'html-embed' : 'default')) as AppTemplate;
+  if (!APP_TEMPLATES.includes(template)) {
+    throw new Error(`Unknown template "${template}". Available: ${APP_TEMPLATES.join(', ')}.`);
+  }
+
+  if (opts.htmlFile && !(await pathExists(opts.htmlFile))) {
+    throw new Error(`HTML file does not exist: ${opts.htmlFile}`);
+  }
+
+  // Validate target dir.
+  const appDir = path.join(workspace, appName);
+  if (!(await isDirEmpty(appDir))) {
+    throw new Error(`${appDir} is non-empty. Pick a different name or wipe it first.`);
+  }
+
+  // Check for manifest collision (network call — after all local checks).
+  const manifest = await readManifest();
+  if (manifest[mfAppName(appName)]) {
+    throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
+  }
+
+  // Compute substitutions.
+  const vars = {
+    __APP_NAME__: appName,
+    __APP_COMPONENT__: pascalCase(appName),
+  };
+
+  const appTemplatesDir = path.join(getTemplatesDir(), 'app');
+  await ensureDir(path.join(appDir, 'src'));
+  await ensureDir(path.join(appDir, '.claude'));
+
+  // package.json (templated).
+  const pkgRaw = await readFile(path.join(appTemplatesDir, 'package.json.tmpl'), 'utf8');
+  await writeFile(path.join(appDir, 'package.json'), renderTemplate(pkgRaw, vars));
+
+  // src/index.tsx (templated; choice driven by template).
+  const indexTemplate = template === 'html-embed' ? 'html-index.tsx.tmpl' : 'default-index.tsx.tmpl';
+  const indexRaw = await readFile(path.join(appTemplatesDir, indexTemplate), 'utf8');
+  await writeFile(path.join(appDir, 'src', 'index.tsx'), renderTemplate(indexRaw, vars));
+
+  // Copy verbatim files.
+  await copy(path.join(appTemplatesDir, 'gitignore'), path.join(appDir, '.gitignore'));
+  await copy(path.join(appTemplatesDir, 'claude-settings.json'), path.join(appDir, '.claude', 'settings.json'));
+  await copy(path.join(appTemplatesDir, 'CLAUDE.md'), path.join(appDir, 'CLAUDE.md'));
+
+  // html-embed: also copy the source HTML.
+  if (template === 'html-embed' && opts.htmlFile) {
+    await copy(opts.htmlFile, path.join(appDir, 'src', 'page.html'));
+  }
+
+  info(`installing into workspace at ${workspace}`);
+  await execa('yarn', ['install'], {
+    cwd: workspace,
+    stdio: 'inherit',
+  });
+
+  output(`[z2h-cli] app ready at ${appDir}`, {
+    ok: true,
+    appDir,
+    appName,
+    template,
+  });
+}

package/src/commands/deploy.ts

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import os from 'node:os';
 import { pathExists, readJson } from 'fs-extra';
 import { execa } from 'execa';
 import { info, warn, output, setOutputMode } from '../util/logger';
@@ -42,9 +43,6 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
   info('checking S3 bucket');
   await assertBucketExists();
 
-  info('building');
-  await buildCommand({ json: opts.json });
-
   const paths = resolveConsumerPaths(process.cwd());
   const consumerPkg = (await readJson(paths.consumerPkg)) as { name?: string };
   if (!consumerPkg.name) {
@@ -52,6 +50,15 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
   }
   const appName = mfAppName(consumerPkg.name);
 
+  info('reading current Z2H manifest');
+  const manifest = await readManifest();
+  const version = nextVersion(manifest, appName);
+  const keyPrefix = `${appName}/${version}`;
+  const url = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
+
+  info('building');
+  await buildCommand({ json: opts.json, publicUrl: url });
+
   if (!(await pathExists(paths.shadowBuild))) {
     throw new Error(`No build output at ${paths.shadowBuild} after build step.`);
   }
@@ -63,12 +70,6 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
   }
   const assetManifest = (await readJson(assetManifestPath)) as AssetManifestFile;
 
-  info('reading current Z2H manifest');
-  const manifest = await readManifest();
-  const version = nextVersion(manifest, appName);
-  const keyPrefix = `${appName}/${version}`;
-  const url = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
-
   if (opts.dryRun) {
     output(`[z2h-cli] dry-run: would upload to s3://${BUCKET_WRITE_NAME}/${keyPrefix}/ as v${version}`, {
       ok: true,
@@ -85,15 +86,18 @@ export async function deployCommand(opts: DeployOptions): Promise<void> {
 
   await requestAponoAccess();
 
-  info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
-  await uploadDir(paths.shadowBuild, keyPrefix);
+  const deployedBy = os.userInfo().username;
 
   const entry: ManifestEntry = {
     ...assetManifest,
     version,
     url,
+    deployedBy,
   };
 
+  info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
+  await uploadDir(paths.shadowBuild, keyPrefix);
+
   info(`updating manifest entry "${appName}" → v${version}`);
   await writeManifest(upsertEntry(manifest, appName, entry));
 

package/src/commands/dev.ts

@@ -1,4 +1,6 @@
-import { readJson } from 'fs-extra';
+import path from 'node:path';
+import fs from 'node:fs';
+import { readJson, writeFile } from 'fs-extra';
 import { watch } from 'chokidar';
 import { execa } from 'execa';
 import { info, warn, errorLog, output, setOutputMode } from '../util/logger';
@@ -31,6 +33,29 @@ export async function devCommand(opts: DevOptions): Promise<void> {
     stdio: ['inherit', 'pipe', 'inherit'],
   });
 
+  const pidFile = path.join(ctx.paths.shadowDir, 'dev.pid');
+  if (server.pid) {
+    await writeFile(pidFile, String(server.pid));
+  }
+
+  const cleanupPid = () => {
+    try {
+      fs.unlinkSync(pidFile);
+    } catch (_) {
+      // file already gone — ignore
+    }
+  };
+  server.on('exit', cleanupPid);
+  process.on('exit', cleanupPid);
+  process.on('SIGINT', () => {
+    server.kill();
+    process.exit(0);
+  });
+  process.on('SIGTERM', () => {
+    server.kill();
+    process.exit(0);
+  });
+
   let readyPrinted = false;
   server.stdout?.on('data', (chunk: Buffer) => {
     process.stdout.write(chunk);